@timber-js/app 0.2.0-alpha.61 → 0.2.0-alpha.63

package/src/server/rsc-entry/ssr-bridge.ts

@@ -10,9 +10,18 @@ export async function callSsr(
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
 ): Promise<Response> {
-  const ssrEntry = await import.meta.viteRsc.import<typeof import('../ssr-entry.js')>(
-    '../ssr-entry.js',
-    { environment: 'ssr' }
-  );
+  let ssrEntry: typeof import('../ssr-entry.js');
+  try {
+    ssrEntry = await import.meta.viteRsc.import<typeof import('../ssr-entry.js')>(
+      '../ssr-entry.js',
+      { environment: 'ssr' }
+    );
+  } catch (error) {
+    const original = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `[timber] Failed to load SSR entry from RSC environment.\n  ${original}\n  This usually means a module evaluation error in the SSR bundle.`,
+      { cause: error }
+    );
+  }
   return ssrEntry.handleSsr(rscStream, navContext);
 }

package/src/server/safe-load.ts

@@ -0,0 +1,60 @@
+/**
+ * loadModule — enriched error context for route manifest .load() failures.
+ *
+ * Wraps the lazy `load()` functions from the route manifest with a
+ * try/catch that re-throws with the file path and original cause.
+ *
+ * Callers that need fallthrough behavior (error renderers) can use
+ * `.catch(() => null)` or try/catch — the decision stays at the call site.
+ *
+ * See design/spike-TIM-551-dynamic-import-audit.md §"Proposed Wrapping Strategy"
+ */
+
+/** A manifest file reference with a lazy import function and file path. */
+export interface ManifestLoader {
+  load: () => Promise<unknown>;
+  filePath: string;
+}
+
+/**
+ * Custom error class for module load failures.
+ *
+ * Preserves the original error as `cause` while providing a
+ * human-readable message with the file path.
+ */
+export class ModuleLoadError extends Error {
+  /** The file path that failed to load. */
+  readonly filePath: string;
+
+  constructor(filePath: string, cause: unknown) {
+    const originalMessage = cause instanceof Error ? cause.message : String(cause);
+    super(`[timber] Failed to load module ${filePath}\n  ${originalMessage}`, { cause });
+    this.name = 'ModuleLoadError';
+    this.filePath = filePath;
+  }
+}
+
+/**
+ * Load a route manifest module with enriched error context.
+ *
+ * On success: returns the module object (same as `loader.load()`).
+ * On failure: throws `ModuleLoadError` with file path and original cause.
+ *
+ * For error rendering paths that need fallthrough instead of throwing,
+ * callers should catch at the call site:
+ *
+ * ```ts
+ * // Throwing (default) — route-element-builder, api-handler, etc.
+ * const mod = await loadModule(segment.page);
+ *
+ * // Fallthrough — error-renderer, error-boundary-wrapper
+ * const mod = await loadModule(segment.error).catch(() => null);
+ * ```
+ */
+export async function loadModule<T = Record<string, unknown>>(loader: ManifestLoader): Promise<T> {
+  try {
+    return (await loader.load()) as T;
+  } catch (error) {
+    throw new ModuleLoadError(loader.filePath, error);
+  }
+}

package/src/server/slot-resolver.ts

@@ -20,6 +20,7 @@ import { TimberErrorBoundary } from '../client/error-boundary.js';
 import SlotErrorFallback from '../client/slot-error-fallback.js';
 import { SlotAccessGate } from './access-gate.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
+import { loadModule } from './safe-load.js';
 import type { InterceptionContext, RouteMatch } from './pipeline.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
 import { logRenderError } from './logger.js';
@@ -35,8 +36,9 @@ type CreateElementFn = (...args: unknown[]) => React.ReactElement;
  */
 async function loadComponent(loader: {
   load: () => Promise<unknown>;
+  filePath: string;
 }): Promise<((...args: unknown[]) => unknown) | undefined> {
-  const mod = (await loader.load()) as Record<string, unknown>;
+  const mod = await loadModule(loader);
   return mod.default as ((...args: unknown[]) => unknown) | undefined;
 }
 

package/src/server/tracing.ts

@@ -110,9 +110,20 @@ export async function initDevTracing(
   const api = await getOtelApi();
   if (!api) return;
 
-  const { DevSpanProcessor } = await import('./dev-span-processor.js');
-  const { BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base');
-  const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');
+  let DevSpanProcessor: typeof import('./dev-span-processor.js').DevSpanProcessor;
+  let BasicTracerProvider: typeof import('@opentelemetry/sdk-trace-base').BasicTracerProvider;
+  let AsyncLocalStorageContextManager: typeof import('@opentelemetry/context-async-hooks').AsyncLocalStorageContextManager;
+
+  try {
+    ({ DevSpanProcessor } = await import('./dev-span-processor.js'));
+    ({ BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base'));
+    ({ AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks'));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[timber] Dev tracing disabled — failed to load OTEL packages:\n  ${msg}`);
+    return;
+  }
+
   const processor = new DevSpanProcessor(config);
 
   // Register a context manager so OTEL can propagate the active span

package/dist/_chunks/interception-Cey5DCGr.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"interception-Cey5DCGr.js","names":[],"sources":["../../src/routing/types.ts","../../src/routing/scanner.ts","../../src/routing/codegen.ts","../../src/routing/interception.ts"],"sourcesContent":["/**\n * Route tree types for timber.js file-system routing.\n *\n * The route tree is built by scanning the app/ directory and recognizing\n * file conventions (page.*, layout.*, middleware.ts, access.ts, route.ts, etc.).\n */\n\n/** Segment type classification */\nexport type SegmentType =\n  | 'static' // e.g. \"dashboard\"\n  | 'dynamic' // e.g. \"[id]\"\n  | 'catch-all' // e.g. \"[...slug]\"\n  | 'optional-catch-all' // e.g. \"[[...slug]]\"\n  | 'group' // e.g. \"(marketing)\"\n  | 'slot' // e.g. \"@sidebar\"\n  | 'intercepting' // e.g. \"(.)photo\", \"(..)photo\", \"(...)photo\"\n  | 'private'; // e.g. \"_components\", \"_lib\" — excluded from routing\n\n/**\n * Intercepting route marker — indicates how many levels up to resolve the\n * intercepted route from the intercepting route's location.\n *\n * See design/07-routing.md §\"Intercepting Routes\"\n */\nexport type InterceptionMarker = '(.)' | '(..)' | '(...)' | '(..)(..)';\n\n/** All recognized interception markers, ordered longest-first for parsing. */\nexport const INTERCEPTION_MARKERS: InterceptionMarker[] = ['(..)(..)', '(.)', '(..)', '(...)'];\n\n/** A single file discovered in a route segment */\nexport interface RouteFile {\n  /** Absolute path to the file */\n  filePath: string;\n  /** File extension without leading dot (e.g. \"tsx\", \"ts\", \"mdx\") */\n  extension: string;\n}\n\n/** A node in the segment tree */\nexport interface SegmentNode {\n  /** The raw directory name (e.g. \"dashboard\", \"[id]\", \"(auth)\", \"@sidebar\") */\n  segmentName: string;\n  /** Classified segment type */\n  segmentType: SegmentType;\n  /** The dynamic param name, if dynamic (e.g. \"id\" for \"[id]\", \"slug\" for \"[...slug]\") */\n  paramName?: string;\n  /** The URL path prefix at this segment level (e.g. \"/dashboard\") */\n  urlPath: string;\n  /** For intercepting segments: the marker used, e.g. \"(.)\". */\n  interceptionMarker?: InterceptionMarker;\n  /**\n   * For intercepting segments: the segment name after stripping the marker.\n   * E.g., for \"(.)photo\" this is \"photo\".\n   */\n  interceptedSegmentName?: string;\n\n  // --- File conventions ---\n  page?: RouteFile;\n  layout?: RouteFile;\n  middleware?: RouteFile;\n  access?: RouteFile;\n  route?: RouteFile;\n  /**\n   * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.\n   * Discovered by the scanner like middleware.ts and access.ts.\n   * See design/07-routing.md §\"params.ts Convention File\"\n   */\n  params?: RouteFile;\n  error?: RouteFile;\n  default?: RouteFile;\n  /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */\n  statusFiles?: Map<string, RouteFile>;\n  /** JSON status-code files: 4xx.json, 5xx.json, {status}.json */\n  jsonStatusFiles?: Map<string, RouteFile>;\n  /** denied.tsx — slot-only denial rendering */\n  denied?: RouteFile;\n  /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */\n  legacyStatusFiles?: Map<string, RouteFile>;\n\n  /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */\n  metadataRoutes?: Map<string, RouteFile>;\n\n  // --- Children ---\n  children: SegmentNode[];\n  /** Parallel route slots (keyed by slot name without @) */\n  slots: Map<string, SegmentNode>;\n}\n\n/** The full route tree output from the scanner */\nexport interface RouteTree {\n  /** The root segment node (representing app/) */\n  root: SegmentNode;\n  /** All discovered proxy.ts files (should be at most one, in app/) */\n  proxy?: RouteFile;\n  /**\n   * Global error page: app/global-error.{tsx,ts,jsx,js}\n   *\n   * Rendered as a standalone full-page replacement (no layout wrapping)\n   * when no segment-level error file is found. SSR-only render path.\n   * Must provide its own <html> and <body>.\n   *\n   * See design/10-error-handling.md §\"Tier 2 — Global Error Page\"\n   */\n  globalError?: RouteFile;\n}\n\n/** Configuration passed to the scanner */\nexport interface ScannerConfig {\n  /** Recognized page/layout extensions (without dots). Default: ['tsx', 'ts', 'jsx', 'js'] */\n  pageExtensions?: string[];\n}\n\n/** Default page extensions */\nexport const DEFAULT_PAGE_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js'];\n","/**\n * Route discovery scanner.\n *\n * Pure function: (appDir, config) → RouteTree\n *\n * Scans the app/ directory and builds a segment tree recognizing all\n * timber.js file conventions. Does NOT handle request matching — this\n * is discovery only.\n */\n\nimport { readdirSync, statSync } from 'node:fs';\nimport { join, extname, basename } from 'node:path';\nimport type {\n  RouteTree,\n  SegmentNode,\n  SegmentType,\n  RouteFile,\n  ScannerConfig,\n  InterceptionMarker,\n} from './types.js';\nimport { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';\nimport { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';\n\n/**\n * Pattern matching encoded path delimiters that must be rejected during route discovery.\n * %2F / %2f (forward slash) and %5C / %5c (backslash) can cause route collisions\n * when decoded. See design/13-security.md §\"Encoded separators rejected\".\n */\nconst ENCODED_SEPARATOR_PATTERN = /%(?:2[fF]|5[cC])/;\n\n/**\n * Pattern matching encoded null bytes (%00) that must be rejected.\n * See design/13-security.md §\"Null bytes rejected\".\n */\nconst ENCODED_NULL_PATTERN = /%00/;\n\n/**\n * File convention names that use pageExtensions (can be .tsx, .ts, .jsx, .js, .mdx, etc.)\n */\nconst PAGE_EXT_CONVENTIONS = new Set(['page', 'layout', 'error', 'default', 'denied']);\n\n/**\n * Legacy compat status-code files.\n * Maps legacy file name → HTTP status code for the fallback chain.\n * See design/10-error-handling.md §\"Fallback Chain\".\n */\nconst LEGACY_STATUS_FILES: Record<string, number> = {\n  'not-found': 404,\n  'forbidden': 403,\n  'unauthorized': 401,\n};\n\n/**\n * File convention names that are always .ts/.tsx (never .mdx etc.)\n */\nconst FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'params']);\n\n/**\n * Status-code file patterns:\n * - Exact 3-digit codes: 401.tsx, 429.tsx, 503.tsx\n * - Category catch-alls: 4xx.tsx, 5xx.tsx\n */\nconst STATUS_CODE_PATTERN = /^(\\d{3}|[45]xx)$/;\n\n/**\n * Scan the app/ directory and build the route tree.\n *\n * @param appDir - Absolute path to the app/ directory\n * @param config - Scanner configuration\n * @returns The complete route tree\n */\nexport function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTree {\n  const pageExtensions = config.pageExtensions ?? DEFAULT_PAGE_EXTENSIONS;\n  const extSet = new Set(pageExtensions);\n\n  const tree: RouteTree = {\n    root: createSegmentNode('', 'static', '/'),\n  };\n\n  // Check for proxy.ts at app root\n  const proxyFile = findFixedFile(appDir, 'proxy');\n  if (proxyFile) {\n    tree.proxy = proxyFile;\n  }\n\n  // Check for global-error.{tsx,ts,jsx,js} at app root.\n  // Tier 2 error page — renders standalone (no layouts) when no segment-level\n  // error file is found. See design/10-error-handling.md §\"Tier 2\".\n  const globalErrorFile = findPageExtFile(appDir, 'global-error', extSet);\n  if (globalErrorFile) {\n    tree.globalError = globalErrorFile;\n  }\n\n  // Scan the root directory's files\n  scanSegmentFiles(appDir, tree.root, extSet);\n\n  // Scan children recursively\n  scanChildren(appDir, tree.root, extSet);\n\n  // Validate: detect route group collisions (different groups producing pages at the same URL)\n  validateRouteGroupCollisions(tree.root);\n\n  // Validate: detect duplicate param names in nested dynamic segments\n  // e.g., /[id]/items/[id] — same param name in ancestor and descendant\n  validateDuplicateParamNames(tree.root);\n\n  return tree;\n}\n\n/**\n * Create an empty segment node.\n */\nfunction createSegmentNode(\n  segmentName: string,\n  segmentType: SegmentType,\n  urlPath: string,\n  paramName?: string,\n  interceptionMarker?: InterceptionMarker,\n  interceptedSegmentName?: string\n): SegmentNode {\n  return {\n    segmentName,\n    segmentType,\n    urlPath,\n    paramName,\n    interceptionMarker,\n    interceptedSegmentName,\n    children: [],\n    slots: new Map(),\n  };\n}\n\n/**\n * Classify a directory name into its segment type.\n */\nexport function classifySegment(dirName: string): {\n  type: SegmentType;\n  paramName?: string;\n  interceptionMarker?: InterceptionMarker;\n  interceptedSegmentName?: string;\n} {\n  // Private folder: _name (excluded from routing)\n  if (dirName.startsWith('_')) {\n    return { type: 'private' };\n  }\n\n  // Parallel route slot: @name\n  if (dirName.startsWith('@')) {\n    return { type: 'slot' };\n  }\n\n  // Intercepting routes: (.)name, (..)name, (...)name, (..)(..)name\n  // Check before route groups since intercepting markers also start with (\n  const interception = parseInterceptionMarker(dirName);\n  if (interception) {\n    return {\n      type: 'intercepting',\n      interceptionMarker: interception.marker,\n      interceptedSegmentName: interception.segmentName,\n    };\n  }\n\n  // Route group: (name)\n  if (dirName.startsWith('(') && dirName.endsWith(')')) {\n    return { type: 'group' };\n  }\n\n  // Optional catch-all: [[...name]]\n  if (dirName.startsWith('[[...') && dirName.endsWith(']]')) {\n    const paramName = dirName.slice(5, -2);\n    return { type: 'optional-catch-all', paramName };\n  }\n\n  // Catch-all: [...name]\n  if (dirName.startsWith('[...') && dirName.endsWith(']')) {\n    const paramName = dirName.slice(4, -1);\n    return { type: 'catch-all', paramName };\n  }\n\n  // Dynamic: [name]\n  if (dirName.startsWith('[') && dirName.endsWith(']')) {\n    const paramName = dirName.slice(1, -1);\n    return { type: 'dynamic', paramName };\n  }\n\n  return { type: 'static' };\n}\n\n/**\n * Parse an interception marker from a directory name.\n *\n * Returns the marker and the remaining segment name, or null if not an\n * intercepting route. Markers are checked longest-first to avoid (..)\n * matching before (..)(..).\n *\n * Examples:\n *   \"(.)photo\"      → { marker: \"(.)\", segmentName: \"photo\" }\n *   \"(..)feed\"      → { marker: \"(..)\", segmentName: \"feed\" }\n *   \"(...)photos\"   → { marker: \"(...)\", segmentName: \"photos\" }\n *   \"(..)(..)admin\" → { marker: \"(..)(..)\", segmentName: \"admin\" }\n *   \"(marketing)\"   → null (route group, not interception)\n */\nfunction parseInterceptionMarker(\n  dirName: string\n): { marker: InterceptionMarker; segmentName: string } | null {\n  for (const marker of INTERCEPTION_MARKERS) {\n    if (dirName.startsWith(marker)) {\n      const rest = dirName.slice(marker.length);\n      // Must have a segment name after the marker, and the rest must not\n      // be empty or end with ) (which would be a route group like \"(auth)\")\n      if (rest.length > 0 && !rest.endsWith(')')) {\n        return { marker, segmentName: rest };\n      }\n    }\n  }\n  return null;\n}\n\n/**\n * Compute the URL path for a child segment given its parent's URL path.\n * Route groups, slots, and intercepting routes do NOT add URL depth.\n */\nfunction computeUrlPath(parentUrlPath: string, dirName: string, segmentType: SegmentType): string {\n  // Groups, slots, and intercepting routes don't add to URL path\n  if (segmentType === 'group' || segmentType === 'slot' || segmentType === 'intercepting') {\n    return parentUrlPath;\n  }\n\n  const parentPath = parentUrlPath === '/' ? '' : parentUrlPath;\n  return `${parentPath}/${dirName}`;\n}\n\n/**\n * Scan a directory for file conventions and populate the segment node.\n */\nfunction scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string>): void {\n  let entries: string[];\n  try {\n    entries = readdirSync(dirPath);\n  } catch {\n    return;\n  }\n\n  for (const entry of entries) {\n    const fullPath = join(dirPath, entry);\n\n    // Skip directories — handled by scanChildren\n    try {\n      if (statSync(fullPath).isDirectory()) continue;\n    } catch {\n      continue;\n    }\n\n    const ext = extname(entry).slice(1); // remove leading dot\n    const name = basename(entry, `.${ext}`);\n\n    // Page-extension conventions (page, layout, error, default, denied)\n    if (PAGE_EXT_CONVENTIONS.has(name) && extSet.has(ext)) {\n      const file: RouteFile = { filePath: fullPath, extension: ext };\n      switch (name) {\n        case 'page':\n          node.page = file;\n          break;\n        case 'layout':\n          node.layout = file;\n          break;\n        case 'error':\n          node.error = file;\n          break;\n        case 'default':\n          node.default = file;\n          break;\n        case 'denied':\n          node.denied = file;\n          break;\n      }\n      continue;\n    }\n\n    // Fixed conventions (middleware, access, route) — always .ts or .tsx\n    if (FIXED_CONVENTIONS.has(name) && /\\.?[jt]sx?$/.test(ext)) {\n      const file: RouteFile = { filePath: fullPath, extension: ext };\n      switch (name) {\n        case 'middleware':\n          node.middleware = file;\n          break;\n        case 'access':\n          node.access = file;\n          break;\n        case 'route':\n          node.route = file;\n          break;\n        case 'params':\n          node.params = file;\n          break;\n      }\n      continue;\n    }\n\n    // JSON status-code files (401.json, 4xx.json, 503.json, 5xx.json)\n    // Recognized regardless of pageExtensions — .json is a data format, not a page extension.\n    if (STATUS_CODE_PATTERN.test(name) && ext === 'json') {\n      if (!node.jsonStatusFiles) {\n        node.jsonStatusFiles = new Map();\n      }\n      node.jsonStatusFiles.set(name, { filePath: fullPath, extension: ext });\n      continue;\n    }\n\n    // Status-code files (401.tsx, 4xx.tsx, 503.tsx, 5xx.tsx)\n    if (STATUS_CODE_PATTERN.test(name) && extSet.has(ext)) {\n      if (!node.statusFiles) {\n        node.statusFiles = new Map();\n      }\n      node.statusFiles.set(name, { filePath: fullPath, extension: ext });\n      continue;\n    }\n\n    // Legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)\n    if (name in LEGACY_STATUS_FILES && extSet.has(ext)) {\n      if (!node.legacyStatusFiles) {\n        node.legacyStatusFiles = new Map();\n      }\n      node.legacyStatusFiles.set(name, { filePath: fullPath, extension: ext });\n      continue;\n    }\n\n    // Metadata route files (sitemap.ts, robots.ts, icon.tsx, opengraph-image.tsx, etc.)\n    // Both static (.xml, .txt, .png, .ico, etc.) and dynamic (.ts, .tsx) files are recognized.\n    // When both exist for the same base name, dynamic takes precedence.\n    // See design/16-metadata.md §\"Metadata Routes\"\n    const metaInfo = classifyMetadataRoute(entry);\n    if (metaInfo) {\n      if (!node.metadataRoutes) {\n        node.metadataRoutes = new Map();\n      }\n      const existing = node.metadataRoutes.get(name);\n      if (existing) {\n        // Dynamic > static precedence: only overwrite if the new file is dynamic\n        // or the existing file is static (dynamic always wins).\n        const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);\n        const newIsDynamic = isDynamicMetadataExtension(name, ext);\n        if (newIsDynamic || !existingIsDynamic) {\n          node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });\n        }\n      } else {\n        node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });\n      }\n    }\n  }\n\n  // Validate: route.ts + page.* is a hard build error\n  if (node.route && node.page) {\n    throw new Error(\n      `Build error: route.ts and page.* cannot coexist in the same segment.\\n` +\n        `  route.ts: ${node.route.filePath}\\n` +\n        `  page:     ${node.page.filePath}\\n` +\n        `A URL is either an API endpoint or a rendered page, not both.`\n    );\n  }\n}\n\n/**\n * Recursively scan child directories and build the segment tree.\n */\nfunction scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<string>): void {\n  let entries: string[];\n  try {\n    entries = readdirSync(dirPath);\n  } catch {\n    return;\n  }\n\n  for (const entry of entries) {\n    const fullPath = join(dirPath, entry);\n\n    try {\n      if (!statSync(fullPath).isDirectory()) continue;\n    } catch {\n      continue;\n    }\n\n    // Reject directories with encoded path delimiters or null bytes.\n    // These can cause route collisions when decoded at the URL boundary.\n    // See design/13-security.md §\"Encoded separators rejected\" and §\"Null bytes rejected\".\n    if (ENCODED_SEPARATOR_PATTERN.test(entry)) {\n      throw new Error(\n        `Build error: directory name contains an encoded path delimiter (%%2F or %%5C).\\n` +\n          `  Directory: ${fullPath}\\n` +\n          `Encoded separators in directory names cause route collisions when decoded. ` +\n          `Rename the directory to remove the encoded delimiter.`\n      );\n    }\n    if (ENCODED_NULL_PATTERN.test(entry)) {\n      throw new Error(\n        `Build error: directory name contains an encoded null byte (%%00).\\n` +\n          `  Directory: ${fullPath}\\n` +\n          `Encoded null bytes in directory names are not allowed. ` +\n          `Rename the directory to remove the null byte encoding.`\n      );\n    }\n\n    const { type, paramName, interceptionMarker, interceptedSegmentName } = classifySegment(entry);\n\n    // Skip private folders — underscore-prefixed dirs are excluded from routing\n    if (type === 'private') continue;\n\n    const urlPath = computeUrlPath(parentNode.urlPath, entry, type);\n    const childNode = createSegmentNode(\n      entry,\n      type,\n      urlPath,\n      paramName,\n      interceptionMarker,\n      interceptedSegmentName\n    );\n\n    // Scan this segment's files\n    scanSegmentFiles(fullPath, childNode, extSet);\n\n    // Recurse into subdirectories\n    scanChildren(fullPath, childNode, extSet);\n\n    // Attach to parent: slots go into slots map, everything else is a child\n    if (type === 'slot') {\n      const slotName = entry.slice(1); // remove @\n      parentNode.slots.set(slotName, childNode);\n    } else {\n      parentNode.children.push(childNode);\n    }\n  }\n}\n\n/**\n * Validate that route groups don't produce conflicting pages/routes at the same URL path.\n *\n * Two route groups like (auth)/login/page.tsx and (marketing)/login/page.tsx both claim\n * /login — the scanner must detect and reject this at build time.\n *\n * Parallel slots are excluded from collision detection — they intentionally coexist at\n * the same URL path as their parent (that's the whole point of parallel routes).\n */\nfunction validateRouteGroupCollisions(root: SegmentNode): void {\n  // Map from urlPath → { filePath, source } for the first page/route seen at that path\n  const seen = new Map<string, { filePath: string; segmentPath: string }>();\n  collectRoutableLeaves(root, seen, '', false);\n}\n\n/**\n * Walk the segment tree and collect all routable leaves (page or route files),\n * throwing on collision. Slots are tracked in their own collision space since\n * they are parallel routes that intentionally share URL paths with their parent.\n */\nfunction collectRoutableLeaves(\n  node: SegmentNode,\n  seen: Map<string, { filePath: string; segmentPath: string }>,\n  segmentPath: string,\n  insideSlot: boolean\n): void {\n  const currentPath = segmentPath\n    ? `${segmentPath}/${node.segmentName}`\n    : node.segmentName || '(root)';\n\n  // Only check collisions for non-slot pages — slots intentionally share URL paths\n  if (!insideSlot) {\n    const routableFile = node.page ?? node.route;\n    if (routableFile) {\n      const existing = seen.get(node.urlPath);\n      if (existing) {\n        throw new Error(\n          `Build error: route collision — multiple route groups produce a page/route at the same URL path.\\n` +\n            `  URL path: ${node.urlPath}\\n` +\n            `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\\n` +\n            `  File 2:   ${routableFile.filePath} (via ${currentPath})\\n` +\n            `Each URL path must map to exactly one page or route handler. ` +\n            `Rename or move one of the conflicting files.`\n        );\n      }\n      seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });\n    }\n  }\n\n  // Recurse into children\n  for (const child of node.children) {\n    collectRoutableLeaves(child, seen, currentPath, insideSlot);\n  }\n\n  // Recurse into slots — each slot is its own parallel route space\n  for (const [, slotNode] of node.slots) {\n    collectRoutableLeaves(slotNode, seen, currentPath, true);\n  }\n}\n\n/**\n * Validate that no route chain contains duplicate dynamic param names.\n *\n * Example violation:\n *   app/[id]/items/[id]/page.tsx — 'id' appears twice in the ancestor chain.\n *\n * Route groups are transparent — params accumulate through them.\n * Slots are independent — duplicate detection does NOT cross slot boundaries.\n *\n * See design/07-routing.md §\"Duplicate Param Name Detection\"\n */\nfunction validateDuplicateParamNames(root: SegmentNode): void {\n  walkForDuplicateParams(root, new Map());\n}\n\n/**\n * Recursively walk the segment tree, tracking seen param names → segment paths.\n * Throws on the first duplicate found.\n */\nfunction walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): void {\n  // If this node introduces a param name, check for duplicates\n  if (node.paramName) {\n    const existing = seen.get(node.paramName);\n    if (existing) {\n      throw new Error(\n        `[timber] Duplicate param name '${node.paramName}' in route chain.\\n` +\n          `  First defined at: ${existing}\\n` +\n          `  Duplicate at: ${node.urlPath || '/'}\\n` +\n          `  Rename one of the segments to avoid ambiguity.`\n      );\n    }\n    // Add to seen for descendants (use a new Map to avoid polluting siblings)\n    seen = new Map(seen);\n    seen.set(node.paramName, node.urlPath || '/');\n  }\n\n  // Recurse into children (they inherit the accumulated params)\n  for (const child of node.children) {\n    walkForDuplicateParams(child, seen);\n  }\n\n  // Slots are independent parallel routes — start fresh param tracking\n  // (a slot's params don't conflict with the main route's params)\n  for (const [, slotNode] of node.slots) {\n    walkForDuplicateParams(slotNode, new Map(seen));\n  }\n}\n\n/**\n * Find a fixed-extension file (proxy.ts) in a directory.\n */\nfunction findFixedFile(dirPath: string, name: string): RouteFile | undefined {\n  for (const ext of ['ts', 'tsx']) {\n    const fullPath = join(dirPath, `${name}.${ext}`);\n    try {\n      if (statSync(fullPath).isFile()) {\n        return { filePath: fullPath, extension: ext };\n      }\n    } catch {\n      // File doesn't exist\n    }\n  }\n  return undefined;\n}\n\n/**\n * Find a file using the configured page extensions (tsx, ts, jsx, js, mdx, etc.).\n * Used for app-root conventions like global-error that aren't per-segment.\n */\nfunction findPageExtFile(\n  dirPath: string,\n  name: string,\n  extSet: Set<string>\n): RouteFile | undefined {\n  for (const ext of extSet) {\n    const fullPath = join(dirPath, `${name}.${ext}`);\n    try {\n      if (statSync(fullPath).isFile()) {\n        return { filePath: fullPath, extension: ext };\n      }\n    } catch {\n      // File doesn't exist\n    }\n  }\n  return undefined;\n}\n","/**\n * Route map codegen.\n *\n * Walks the scanned RouteTree and generates a TypeScript declaration file\n * mapping every route to its params and searchParams shapes.\n *\n * This runs at build time and in dev (regenerated on file changes).\n * No runtime overhead — purely static type generation.\n */\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { relative, posix } from 'node:path';\nimport type { RouteTree, SegmentNode } from './types.js';\n\n/** A single route entry extracted from the segment tree. */\ninterface RouteEntry {\n  /** URL path pattern (e.g. \"/products/[id]\") */\n  urlPath: string;\n  /** Accumulated params from all ancestor dynamic segments */\n  params: ParamEntry[];\n  /** Whether the page.tsx exports searchParams */\n  hasSearchParams: boolean;\n  /** Absolute path to the page file that exports searchParams (for import paths) */\n  searchParamsPagePath?: string;\n  /** Whether this is an API route (route.ts) vs page route */\n  isApiRoute: boolean;\n}\n\ninterface ParamEntry {\n  name: string;\n  type: 'string' | 'string[]' | 'string[] | undefined';\n  /** When a layout/page exports defineParams, the absolute path to that file. */\n  codecFilePath?: string;\n}\n\n/** Options for route map generation. */\nexport interface CodegenOptions {\n  /** Absolute path to the app/ directory. Required for page searchParams detection. */\n  appDir?: string;\n  /**\n   * Absolute path to the directory where the .d.ts file will be written.\n   * Used to compute correct relative import paths for page files.\n   * Defaults to appDir when not provided (preserves backward compat for tests).\n   */\n  outputDir?: string;\n}\n\n/**\n * Generate a TypeScript declaration file string from a scanned route tree.\n *\n * The output is a `declare module '@timber-js/app'` block containing the Routes\n * interface that maps every route path to its params and searchParams shape.\n */\nexport function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {\n  const routes: RouteEntry[] = [];\n  collectRoutes(tree.root, [], routes);\n\n  // Sort routes alphabetically for deterministic output\n  routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));\n\n  // When outputDir differs from appDir, import paths must be relative to outputDir\n  const importBase = options.outputDir ?? options.appDir;\n\n  return formatDeclarationFile(routes, importBase);\n}\n\n/**\n * Recursively walk the segment tree and collect route entries.\n *\n * A route entry is created for any segment that has a `page` or `route` file.\n * Params accumulate from ancestor dynamic segments.\n */\nfunction collectRoutes(\n  node: SegmentNode,\n  ancestorParams: ParamEntry[],\n  routes: RouteEntry[]\n): void {\n  // Accumulate params from this segment\n  const params = [...ancestorParams];\n  if (node.paramName) {\n    // Check if layout or page exports a params codec for this segment\n    const codecFile = findParamsExport(node);\n    params.push({\n      name: node.paramName,\n      type: paramTypeForSegment(node.segmentType),\n      codecFilePath: codecFile,\n    });\n  }\n\n  // Check if this segment is a leaf route (has page or route file)\n  const isPage = !!node.page;\n  const isApiRoute = !!node.route;\n\n  if (isPage || isApiRoute) {\n    const entry: RouteEntry = {\n      urlPath: node.urlPath,\n      params: [...params],\n      hasSearchParams: false,\n      isApiRoute,\n    };\n\n    // Detect searchParams export from params.ts (primary) or page.tsx (fallback)\n    if (isPage) {\n      if (node.params && fileHasExport(node.params.filePath, 'searchParams')) {\n        entry.hasSearchParams = true;\n        entry.searchParamsPagePath = node.params.filePath;\n      } else if (node.page && fileHasExport(node.page.filePath, 'searchParams')) {\n        entry.hasSearchParams = true;\n        entry.searchParamsPagePath = node.page.filePath;\n      }\n    }\n\n    routes.push(entry);\n  }\n\n  // Recurse into children\n  for (const child of node.children) {\n    collectRoutes(child, params, routes);\n  }\n\n  // Recurse into slots (they share the parent's URL path, but may have their own pages)\n  for (const [, slot] of node.slots) {\n    collectRoutes(slot, params, routes);\n  }\n}\n\n/**\n * Determine the TypeScript type for a segment's param.\n */\nfunction paramTypeForSegment(segmentType: string): ParamEntry['type'] {\n  switch (segmentType) {\n    case 'catch-all':\n      return 'string[]';\n    case 'optional-catch-all':\n      return 'string[] | undefined';\n    default:\n      return 'string';\n  }\n}\n\n/**\n * Check if a file exports a specific named export.\n *\n * Uses a lightweight regex check — not full AST parsing. The actual type\n * extraction happens via the TypeScript compiler in the generated .d.ts.\n */\nfunction fileHasExport(filePath: string, exportName: string): boolean {\n  if (!existsSync(filePath)) return false;\n  try {\n    const content = readFileSync(filePath, 'utf-8');\n    const e = exportName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    return (\n      new RegExp(`export\\\\s+(const|let|var)\\\\s+${e}\\\\b`).test(content) ||\n      new RegExp(`export\\\\s*\\\\{[^}]*\\\\b${e}\\\\b[^}]*\\\\}`).test(content)\n    );\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Find which file exports `segmentParams` for a dynamic segment.\n *\n * Priority: params.ts (convention file) > layout > page.\n * params.ts is the canonical location (TIM-508). Layout/page fallback\n * exists for backward compat during migration.\n */\nfunction findParamsExport(node: SegmentNode): string | undefined {\n  // params.ts convention file — primary location\n  if (node.params && fileHasExport(node.params.filePath, 'segmentParams')) {\n    return node.params.filePath;\n  }\n  // Fallback: layout or page export (legacy, will be removed)\n  if (node.layout && fileHasExport(node.layout.filePath, 'segmentParams')) {\n    return node.layout.filePath;\n  }\n  if (node.page && fileHasExport(node.page.filePath, 'segmentParams')) {\n    return node.page.filePath;\n  }\n  return undefined;\n}\n\n/**\n * Format the collected routes into a TypeScript declaration file.\n */\nfunction formatDeclarationFile(routes: RouteEntry[], importBase?: string): string {\n  const lines: string[] = [];\n\n  lines.push('// This file is auto-generated by timber.js route map codegen.');\n  lines.push('// Do not edit manually. Regenerated on build and in dev mode.');\n  lines.push('');\n  // export {} makes this file a module, so all declare module blocks are\n  // augmentations rather than ambient replacements. Without this, the\n  // declare module blocks would replace the original module types entirely\n  // (removing exports like bindUseQueryStates that aren't listed here).\n  lines.push('export {};');\n  lines.push('');\n  lines.push(\"declare module '@timber-js/app' {\");\n  lines.push('  interface Routes {');\n\n  for (const route of routes) {\n    const paramsType = formatParamsType(route.params, importBase);\n    const searchParamsType = formatSearchParamsType(route, importBase);\n\n    lines.push(`    '${route.urlPath}': {`);\n    lines.push(`      params: ${paramsType}`);\n    lines.push(`      searchParams: ${searchParamsType}`);\n    lines.push(`    }`);\n  }\n\n  lines.push('  }');\n  lines.push('}');\n  lines.push('');\n\n  // Generate @timber-js/app/server augmentation — typed searchParams() generic\n  const pageRoutes = routes.filter((r) => !r.isApiRoute);\n\n  // Note: searchParams() always returns Promise<URLSearchParams>.\n  // Typed parsing is done via definition.parse(searchParams()).\n  // No module augmentation needed for @timber-js/app/server.\n\n  // Generate overloads for @timber-js/app/client\n  const dynamicRoutes = routes.filter((r) => r.params.length > 0);\n\n  if (dynamicRoutes.length > 0 || pageRoutes.length > 0) {\n    lines.push(\"declare module '@timber-js/app/client' {\");\n    lines.push(\n      \"  import type { SearchParamsDefinition, SetParams, QueryStatesOptions, SearchParamCodec } from '@timber-js/app/search-params'\"\n    );\n    lines.push('');\n\n    // useParams overloads\n    if (dynamicRoutes.length > 0) {\n      for (const route of dynamicRoutes) {\n        const paramsType = formatParamsType(route.params, importBase);\n        lines.push(`  export function useSegmentParams(route: '${route.urlPath}'): ${paramsType}`);\n      }\n      lines.push('  export function useSegmentParams(): Record<string, string | string[]>');\n      lines.push('');\n    }\n\n    // useQueryStates overloads\n    if (pageRoutes.length > 0) {\n      lines.push(...formatUseQueryStatesOverloads(pageRoutes, importBase));\n      lines.push('');\n    }\n\n    // Typed Link overloads\n    if (pageRoutes.length > 0) {\n      lines.push('  // Typed Link props per route');\n      lines.push(...formatTypedLinkOverloads(pageRoutes, importBase));\n    }\n\n    lines.push('}');\n    lines.push('');\n  }\n\n  return lines.join('\\n');\n}\n\n/**\n * Format the params type for a route entry.\n */\nfunction formatParamsType(params: ParamEntry[], importBase?: string): string {\n  if (params.length === 0) {\n    return '{}';\n  }\n\n  const fields = params.map((p) => {\n    if (p.codecFilePath) {\n      // Use the codec's inferred type from the layout/page file\n      const absPath = p.codecFilePath.replace(/\\.(ts|tsx)$/, '');\n      let importPath: string;\n      if (importBase) {\n        importPath = './' + relative(importBase, absPath).replace(/\\\\/g, '/');\n      } else {\n        importPath = './' + posix.basename(absPath);\n      }\n      // Extract T from the 'segmentParams' named export's ParamsDefinition<T>\n      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;\n      return `${p.name}: ${codecType}`;\n    }\n    return `${p.name}: ${p.type}`;\n  });\n  return `{ ${fields.join('; ')} }`;\n}\n\n/**\n * Format the params type for Link props.\n *\n * Link params accept `string | number` for single dynamic segments\n * (convenience — values are stringified at runtime). Catch-all and\n * optional catch-all remain `string[]` / `string[] | undefined`.\n *\n * See design/07-routing.md §\"Typed params and searchParams on <Link>\"\n */\nfunction formatLinkParamsType(params: ParamEntry[], importBase?: string): string {\n  if (params.length === 0) {\n    return '{}';\n  }\n\n  const fields = params.map((p) => {\n    if (p.codecFilePath) {\n      // With a codec, Link params use the codec's output type\n      const absPath = p.codecFilePath.replace(/\\.(ts|tsx)$/, '');\n      let importPath: string;\n      if (importBase) {\n        importPath = './' + relative(importBase, absPath).replace(/\\\\/g, '/');\n      } else {\n        importPath = './' + posix.basename(absPath);\n      }\n      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;\n      return `${p.name}: ${codecType}`;\n    }\n    // Single dynamic segments accept string | number for convenience\n    const type = p.type === 'string' ? 'string | number' : p.type;\n    return `${p.name}: ${type}`;\n  });\n  return `{ ${fields.join('; ')} }`;\n}\n\n/**\n * Format the searchParams type for a route entry.\n *\n * When a page.tsx exports searchParams, we reference its inferred type via an import type.\n * The import path is relative to `importBase` (the directory where the .d.ts will be\n * written). When importBase is undefined, falls back to a bare relative path.\n */\nfunction formatSearchParamsType(route: RouteEntry, importBase?: string): string {\n  if (route.hasSearchParams && route.searchParamsPagePath) {\n    const absPath = route.searchParamsPagePath.replace(/\\.(ts|tsx)$/, '');\n    let importPath: string;\n    if (importBase) {\n      // Make the path relative to the output directory, converted to posix separators\n      importPath = './' + relative(importBase, absPath).replace(/\\\\/g, '/');\n    } else {\n      importPath = './' + posix.basename(absPath);\n    }\n    // Extract the type from the named 'searchParams' export of the page module.\n    return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;\n  }\n  return '{}';\n}\n\n/**\n * Generate useQueryStates overloads.\n *\n * For each page route:\n * - Routes with search-params.ts get a typed overload returning the inferred T\n * - Routes without search-params.ts get an overload returning [{}, SetParams<{}>]\n *\n * A fallback overload for standalone codecs (existing API) is emitted last.\n */\nfunction formatUseQueryStatesOverloads(routes: RouteEntry[], importBase?: string): string[] {\n  const lines: string[] = [];\n\n  for (const route of routes) {\n    const searchParamsType = route.hasSearchParams\n      ? formatSearchParamsType(route, importBase)\n      : '{}';\n    lines.push(\n      `  export function useQueryStates<R extends '${route.urlPath}'>(route: R, options?: QueryStatesOptions): [${searchParamsType}, SetParams<${searchParamsType}>]`\n    );\n  }\n\n  // Fallback: standalone codecs (existing API)\n  lines.push(\n    '  export function useQueryStates<T extends Record<string, unknown>>(codecs: { [K in keyof T]: SearchParamCodec<T[K]> }, options?: QueryStatesOptions): [T, SetParams<T>]'\n  );\n\n  return lines;\n}\n\n/**\n * Generate typed Link overloads.\n *\n * For each page route, we generate a Link function overload that:\n * - Constrains href to the route pattern\n * - Types the params prop based on dynamic segments\n * - Types the searchParams prop based on search-params.ts (if present)\n *\n * Routes without dynamic segments accept href as a literal string with no params.\n * Routes with dynamic segments require a params prop.\n */\nfunction formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {\n  const lines: string[] = [];\n\n  for (const route of routes) {\n    const hasDynamicParams = route.params.length > 0;\n    const paramsProp = hasDynamicParams\n      ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}`\n      : 'segmentParams?: never';\n\n    const searchParamsType = route.hasSearchParams\n      ? formatSearchParamsType(route, importBase)\n      : null;\n    const searchParamsProp = searchParamsType\n      ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`\n      : 'searchParams?: never';\n\n    lines.push(\n      `  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`\n    );\n    lines.push(`    href: '${route.urlPath}'`);\n    lines.push(`    ${paramsProp}`);\n    lines.push(`    ${searchParamsProp}`);\n    lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);\n    lines.push(`  }): import('react').JSX.Element`);\n  }\n\n  // Fallback overload for arbitrary string hrefs (escape hatch)\n  lines.push(\n    `  export function Link(props: import('./client/link.js').LinkProps): import('react').JSX.Element`\n  );\n\n  return lines;\n}\n","/**\n * Intercepting route utilities.\n *\n * Computes rewrite rules from the route tree that enable intercepting routes\n * to conditionally render when navigating via client-side (soft) navigation.\n *\n * The mechanism: at build time, each intercepting route directory generates a\n * conditional rewrite. On soft navigation, the client sends an `X-Timber-URL`\n * header with the current pathname. The server checks if any rewrite's source\n * (the intercepted URL) matches the target pathname AND the header matches\n * the intercepting route's parent URL. If both match, the intercepting route\n * renders instead of the normal route.\n *\n * On hard navigation (no header), no rewrite matches, and the normal route\n * renders.\n *\n * See design/07-routing.md §\"Intercepting Routes\"\n */\n\nimport type { SegmentNode, InterceptionMarker } from './types.js';\n\n/** A conditional rewrite rule generated from an intercepting route. */\nexport interface InterceptionRewrite {\n  /**\n   * The URL pattern that this rewrite intercepts (the target of navigation).\n   * E.g., \"/photo/[id]\" for a (.)photo/[id] interception.\n   */\n  interceptedPattern: string;\n  /**\n   * The URL prefix that the client must be navigating FROM for this rewrite\n   * to apply. Matched against the X-Timber-URL header.\n   * E.g., \"/feed\" for a (.)photo/[id] inside /feed/@modal/.\n   */\n  interceptingPrefix: string;\n  /**\n   * Segments chain from root → intercepting leaf. Used to build the element\n   * tree when the interception is active.\n   */\n  segmentPath: SegmentNode[];\n}\n\n/**\n * Collect all interception rewrite rules from the route tree.\n *\n * Walks the tree recursively. For each intercepting segment, computes the\n * intercepted URL based on the marker and the segment's position.\n */\nexport function collectInterceptionRewrites(root: SegmentNode): InterceptionRewrite[] {\n  const rewrites: InterceptionRewrite[] = [];\n  walkForInterceptions(root, [root], rewrites);\n  return rewrites;\n}\n\n/**\n * Recursively walk the segment tree to find intercepting routes.\n */\nfunction walkForInterceptions(\n  node: SegmentNode,\n  ancestors: SegmentNode[],\n  rewrites: InterceptionRewrite[]\n): void {\n  // Check children\n  for (const child of node.children) {\n    if (child.segmentType === 'intercepting' && child.interceptionMarker) {\n      // Found an intercepting route — collect rewrites from its sub-tree\n      collectFromInterceptingNode(child, ancestors, rewrites);\n    } else {\n      walkForInterceptions(child, [...ancestors, child], rewrites);\n    }\n  }\n\n  // Check slots (intercepting routes are typically inside slots like @modal)\n  for (const [, slot] of node.slots) {\n    walkForInterceptions(slot, ancestors, rewrites);\n  }\n}\n\n/**\n * For an intercepting segment, find all leaf pages in its sub-tree and\n * generate rewrite rules for each.\n */\nfunction collectFromInterceptingNode(\n  interceptingNode: SegmentNode,\n  ancestors: SegmentNode[],\n  rewrites: InterceptionRewrite[]\n): void {\n  const marker = interceptingNode.interceptionMarker!;\n  const segmentName = interceptingNode.interceptedSegmentName!;\n\n  // Compute the intercepted URL base based on the marker\n  const parentUrlPath = ancestors[ancestors.length - 1].urlPath;\n  const interceptedBase = computeInterceptedBase(parentUrlPath, marker);\n  const interceptedUrlBase =\n    interceptedBase === '/' ? `/${segmentName}` : `${interceptedBase}/${segmentName}`;\n\n  // Find all leaf pages in the intercepting sub-tree\n  collectLeavesWithRewrites(\n    interceptingNode,\n    interceptedUrlBase,\n    parentUrlPath,\n    [...ancestors, interceptingNode],\n    rewrites\n  );\n}\n\n/**\n * Recursively find leaf pages in an intercepting sub-tree and generate\n * rewrite rules for each.\n */\nfunction collectLeavesWithRewrites(\n  node: SegmentNode,\n  interceptedUrlPath: string,\n  interceptingPrefix: string,\n  segmentPath: SegmentNode[],\n  rewrites: InterceptionRewrite[]\n): void {\n  if (node.page) {\n    rewrites.push({\n      interceptedPattern: interceptedUrlPath,\n      interceptingPrefix,\n      segmentPath: [...segmentPath],\n    });\n  }\n\n  for (const child of node.children) {\n    const childUrl =\n      child.segmentType === 'group'\n        ? interceptedUrlPath\n        : `${interceptedUrlPath}/${child.segmentName}`;\n    collectLeavesWithRewrites(\n      child,\n      childUrl,\n      interceptingPrefix,\n      [...segmentPath, child],\n      rewrites\n    );\n  }\n}\n\n/**\n * Compute the base URL that an intercepting route intercepts, given the\n * parent's URL path and the interception marker.\n *\n * - (.)  — same level: parent's URL path\n * - (..) — one level up: parent's parent URL path\n * - (...) — root level: /\n * - (..)(..) — two levels up: parent's grandparent URL path\n *\n * Level counting operates on URL path segments, NOT filesystem directories.\n * Route groups and parallel slots are already excluded from urlPath (they\n * don't add URL depth), so (..) correctly climbs visible segments. This\n * avoids the Vinext bug where path.dirname() on filesystem paths would\n * waste climbs on invisible route groups.\n */\nfunction computeInterceptedBase(parentUrlPath: string, marker: InterceptionMarker): string {\n  switch (marker) {\n    case '(.)':\n      return parentUrlPath;\n    case '(..)': {\n      const parts = parentUrlPath.split('/').filter(Boolean);\n      parts.pop();\n      return parts.length === 0 ? '/' : `/${parts.join('/')}`;\n    }\n    case '(...)':\n      return '/';\n    case '(..)(..)': {\n      const parts = parentUrlPath.split('/').filter(Boolean);\n      parts.pop();\n      parts.pop();\n      return parts.length === 0 ? '/' : `/${parts.join('/')}`;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/_chunks/tracing-VYETCQsg.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracing-VYETCQsg.js","names":[],"sources":["../../src/server/tracing.ts"],"sourcesContent":["/**\n * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.\n *\n * traceId() is always available in server code (middleware, access, components, actions).\n * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,\n * or a crypto.randomUUID()-derived fallback otherwise.\n *\n * See design/17-logging.md §\"trace_id is Always Set\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { traceAls, type TraceStore } from './als-registry.js';\n\n// Re-export the TraceStore type for public API consumers.\nexport type { TraceStore } from './als-registry.js';\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns the current request's trace ID — always a 32-char lowercase hex string.\n *\n * With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).\n * Without OTEL: crypto.randomUUID() with hyphens stripped.\n *\n * Throws if called outside a request context (no ALS store).\n */\nexport function traceId(): string {\n  const store = traceAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] traceId() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.traceId;\n}\n\n/**\n * Returns the current OTEL span ID if available, undefined otherwise.\n */\nexport function spanId(): string | undefined {\n  return traceAls.getStore()?.spanId;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Generate a 32-char lowercase hex ID from crypto.randomUUID().\n * Same format as OTEL trace IDs — zero-friction upgrade path.\n */\nexport function generateTraceId(): string {\n  return randomUUID().replace(/-/g, '');\n}\n\n/**\n * Run a callback within a trace context. Used by the pipeline to establish\n * per-request ALS scope.\n */\nexport function runWithTraceId<T>(id: string, fn: () => T): T {\n  return traceAls.run({ traceId: id }, fn);\n}\n\n/**\n * Replace the trace ID in the current ALS store. Used when OTEL creates\n * a root span and we want to switch from the UUID fallback to the real\n * OTEL trace ID.\n */\nexport function replaceTraceId(newTraceId: string, newSpanId?: string): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.traceId = newTraceId;\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Update the span ID in the current ALS store. Used when entering a new\n * OTEL span to keep log–trace correlation accurate.\n */\nexport function updateSpanId(newSpanId: string | undefined): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Get the current trace store, or undefined if outside a request context.\n * Framework-internal — use traceId()/spanId() in user code.\n */\nexport function getTraceStore(): TraceStore | undefined {\n  return traceAls.getStore();\n}\n\n// ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────\n\n/**\n * Initialize a minimal OTEL SDK in dev mode so spans are recorded and\n * fed to the DevSpanProcessor for dev log output.\n *\n * If the user already configured an OTEL SDK in register(), we add\n * our DevSpanProcessor alongside theirs. If no SDK is configured,\n * we create a BasicTracerProvider with our processor.\n *\n * Only called in dev mode — zero overhead in production.\n */\nexport async function initDevTracing(\n  config: import('./dev-logger.js').DevLoggerConfig\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const { DevSpanProcessor } = await import('./dev-span-processor.js');\n  const { BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base');\n  const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');\n  const processor = new DevSpanProcessor(config);\n\n  // Register a context manager so OTEL can propagate the active span\n  // across async boundaries. Without this, startActiveSpan can't make\n  // spans \"active\" — child spans get random trace IDs and getActiveSpan()\n  // returns undefined.\n  const contextManager = new AsyncLocalStorageContextManager();\n  contextManager.enable();\n  api.context.setGlobalContextManager(contextManager);\n\n  // Create a minimal TracerProvider with our DevSpanProcessor.\n  // If the user also configures an SDK in register(), their provider\n  // will coexist — the global provider set last wins for new tracers,\n  // but our processor captures all spans from the timber.js tracer.\n  const provider = new BasicTracerProvider({\n    spanProcessors: [processor],\n  });\n  api.trace.setGlobalTracerProvider(provider);\n\n  // Reset cached tracer so next getTracer() picks up the new provider\n  _tracer = undefined;\n}\n\n// ─── OTEL Span Helpers ───────────────────────────────────────────────────\n\n/**\n * Attempt to get the @opentelemetry/api tracer. Returns undefined if the\n * package is not installed or no SDK is registered.\n *\n * timber.js depends on @opentelemetry/api as the vendor-neutral interface.\n * The API is a no-op by default — spans are only emitted when the developer\n * initializes an SDK in register().\n */\nlet _otelApi: typeof import('@opentelemetry/api') | null | undefined;\n\nasync function getOtelApi(): Promise<typeof import('@opentelemetry/api') | null> {\n  if (_otelApi === undefined) {\n    try {\n      _otelApi = await import('@opentelemetry/api');\n    } catch {\n      _otelApi = null;\n    }\n  }\n  return _otelApi;\n}\n\n/** OTEL tracer instance, lazily created. */\nlet _tracer: import('@opentelemetry/api').Tracer | null | undefined;\n\n/**\n * Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.\n */\nexport async function getTracer(): Promise<import('@opentelemetry/api').Tracer | null> {\n  if (_tracer === undefined) {\n    const api = await getOtelApi();\n    if (api) {\n      _tracer = api.trace.getTracer('timber.js');\n    } else {\n      _tracer = null;\n    }\n  }\n  return _tracer;\n}\n\n/**\n * Run a function within an OTEL span. If OTEL is not available, runs the function\n * directly without any span overhead.\n *\n * Automatically:\n * - Creates the span as a child of the current context\n * - Updates the ALS span ID for log–trace correlation\n * - Ends the span when the function completes\n * - Records exceptions on error\n */\nexport async function withSpan<T>(\n  name: string,\n  attributes: Record<string, string | number | boolean>,\n  fn: () => T | Promise<T>\n): Promise<T> {\n  const tracer = await getTracer();\n  if (!tracer) {\n    return fn();\n  }\n\n  const api = (await getOtelApi())!;\n  return tracer.startActiveSpan(name, { attributes }, async (span) => {\n    const prevSpanId = spanId();\n    updateSpanId(span.spanContext().spanId);\n    try {\n      const result = await fn();\n      span.setStatus({ code: api.SpanStatusCode.OK });\n      return result;\n    } catch (error) {\n      span.setStatus({ code: api.SpanStatusCode.ERROR });\n      if (error instanceof Error) {\n        span.recordException(error);\n      }\n      throw error;\n    } finally {\n      span.end();\n      updateSpanId(prevSpanId);\n    }\n  });\n}\n\n/**\n * Set an attribute on the current active span (if any).\n * Used for setting span attributes after span creation (e.g. timber.result on access spans).\n */\nexport async function setSpanAttribute(\n  key: string,\n  value: string | number | boolean\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.setAttribute(key, value);\n  }\n}\n\n/**\n * Add a span event to the current active span (if any).\n * Used for timber.cache HIT/MISS events — recorded as span events, not child spans.\n */\nexport async function addSpanEvent(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Fire-and-forget span event — no await, no microtask overhead.\n *\n * Used on the cache hot path where awaiting addSpanEvent creates an\n * unnecessary microtask per cache operation. If OTEL is not loaded yet,\n * the event is silently dropped (acceptable for diagnostics).\n *\n * See TIM-370 for perf motivation.\n */\nexport function addSpanEventSync(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): void {\n  // Fast path: if OTEL API hasn't been loaded yet, skip entirely.\n  // _otelApi is undefined (not yet loaded), null (failed to load), or the module.\n  if (!_otelApi) return;\n\n  const activeSpan = _otelApi.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Try to extract the OTEL trace ID from the current active span context.\n * Returns undefined if OTEL is not active or no span exists.\n */\nexport async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {\n  const api = await getOtelApi();\n  if (!api) return undefined;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (!activeSpan) return undefined;\n\n  const ctx = activeSpan.spanContext();\n  // OTEL uses \"0000000000000000\" as invalid trace IDs\n  if (!ctx.traceId || ctx.traceId === '00000000000000000000000000000000') {\n    return undefined;\n  }\n\n  return { traceId: ctx.traceId, spanId: ctx.spanId };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,UAAkB;CAChC,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,CAAC,MACH,OAAM,IAAI,MACR,mJAED;AAEH,QAAO,MAAM;;;;;AAMf,SAAgB,SAA6B;AAC3C,QAAO,SAAS,UAAU,EAAE;;;;;;AAS9B,SAAgB,kBAA0B;AACxC,QAAO,YAAY,CAAC,QAAQ,MAAM,GAAG;;;;;;AAOvC,SAAgB,eAAkB,IAAY,IAAgB;AAC5D,QAAO,SAAS,IAAI,EAAE,SAAS,IAAI,EAAE,GAAG;;;;;;;AAQ1C,SAAgB,eAAe,YAAoB,WAA0B;CAC3E,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,OAAO;AACT,QAAM,UAAU;AAChB,QAAM,SAAS;;;;;;;AAQnB,SAAgB,aAAa,WAAqC;CAChE,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,MACF,OAAM,SAAS;;;;;;AAQnB,SAAgB,gBAAwC;AACtD,QAAO,SAAS,UAAU;;;;;;;;;;AAyD5B,IAAI;AAEJ,eAAe,aAAkE;AAC/E,KAAI,aAAa,KAAA,EACf,KAAI;AACF,aAAW,MAAM,OAAO;SAClB;AACN,aAAW;;AAGf,QAAO;;;AAIT,IAAI;;;;AAKJ,eAAsB,YAAiE;AACrF,KAAI,YAAY,KAAA,GAAW;EACzB,MAAM,MAAM,MAAM,YAAY;AAC9B,MAAI,IACF,WAAU,IAAI,MAAM,UAAU,YAAY;MAE1C,WAAU;;AAGd,QAAO;;;;;;;;;;;;AAaT,eAAsB,SACpB,MACA,YACA,IACY;CACZ,MAAM,SAAS,MAAM,WAAW;AAChC,KAAI,CAAC,OACH,QAAO,IAAI;CAGb,MAAM,MAAO,MAAM,YAAY;AAC/B,QAAO,OAAO,gBAAgB,MAAM,EAAE,YAAY,EAAE,OAAO,SAAS;EAClE,MAAM,aAAa,QAAQ;AAC3B,eAAa,KAAK,aAAa,CAAC,OAAO;AACvC,MAAI;GACF,MAAM,SAAS,MAAM,IAAI;AACzB,QAAK,UAAU,EAAE,MAAM,IAAI,eAAe,IAAI,CAAC;AAC/C,UAAO;WACA,OAAO;AACd,QAAK,UAAU,EAAE,MAAM,IAAI,eAAe,OAAO,CAAC;AAClD,OAAI,iBAAiB,MACnB,MAAK,gBAAgB,MAAM;AAE7B,SAAM;YACE;AACR,QAAK,KAAK;AACV,gBAAa,WAAW;;GAE1B;;;;;;AAOJ,eAAsB,iBACpB,KACA,OACe;CACf,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK;CAEV,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,WACF,YAAW,aAAa,KAAK,MAAM;;;;;;AAQvC,eAAsB,aACpB,MACA,YACe;CACf,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK;CAEV,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,WACF,YAAW,SAAS,MAAM,WAAW;;;;;;;;;;;AAazC,SAAgB,iBACd,MACA,YACM;AAGN,KAAI,CAAC,SAAU;CAEf,MAAM,aAAa,SAAS,MAAM,eAAe;AACjD,KAAI,WACF,YAAW,SAAS,MAAM,WAAW;;;;;;AAQzC,eAAsB,iBAA2E;CAC/F,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK,QAAO,KAAA;CAEjB,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,CAAC,WAAY,QAAO,KAAA;CAExB,MAAM,MAAM,WAAW,aAAa;AAEpC,KAAI,CAAC,IAAI,WAAW,IAAI,YAAY,mCAClC;AAGF,QAAO;EAAE,SAAS,IAAI;EAAS,QAAQ,IAAI;EAAQ"}