@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/routing/codegen.ts

@@ -8,8 +8,8 @@
  * No runtime overhead — purely static type generation.
  */
 
-import { existsSync } from 'node:fs';
-import { join, relative, posix } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { relative, posix } from 'node:path';
 import type { RouteTree, SegmentNode } from './types.js';
 
 /** A single route entry extracted from the segment tree. */
@@ -18,10 +18,10 @@ interface RouteEntry {
   urlPath: string;
   /** Accumulated params from all ancestor dynamic segments */
   params: ParamEntry[];
-  /** Whether this route has a co-located search-params.ts */
+  /** Whether the page.tsx exports searchParams */
   hasSearchParams: boolean;
-  /** Absolute path to search-params.ts (for computing relative import paths) */
-  searchParamsAbsPath?: string;
+  /** Absolute path to the page file that exports searchParams (for import paths) */
+  searchParamsPagePath?: string;
   /** Whether this is an API route (route.ts) vs page route */
   isApiRoute: boolean;
 }
@@ -29,15 +29,17 @@ interface RouteEntry {
 interface ParamEntry {
   name: string;
   type: 'string' | 'string[]' | 'string[] | undefined';
+  /** When a layout/page exports defineParams, the absolute path to that file. */
+  codecFilePath?: string;
 }
 
 /** Options for route map generation. */
 export interface CodegenOptions {
-  /** Absolute path to the app/ directory. Required for search-params.ts detection. */
+  /** Absolute path to the app/ directory. Required for page searchParams detection. */
   appDir?: string;
   /**
    * Absolute path to the directory where the .d.ts file will be written.
-   * Used to compute correct relative import paths for search-params.ts files.
+   * Used to compute correct relative import paths for page files.
    * Defaults to appDir when not provided (preserves backward compat for tests).
    */
   outputDir?: string;
@@ -51,7 +53,7 @@ export interface CodegenOptions {
  */
 export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], options.appDir, routes);
+  collectRoutes(tree.root, [], routes);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -71,15 +73,17 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
 function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
-  appDir: string | undefined,
   routes: RouteEntry[]
 ): void {
   // Accumulate params from this segment
   const params = [...ancestorParams];
   if (node.paramName) {
+    // Check if layout or page exports a params codec for this segment
+    const codecFile = findParamsExport(node);
     params.push({
       name: node.paramName,
       type: paramTypeForSegment(node.segmentType),
+      codecFilePath: codecFile,
     });
   }
 
@@ -95,13 +99,14 @@ function collectRoutes(
       isApiRoute,
     };
 
-    // Detect co-located search-params.ts
-    if (appDir && isPage) {
-      const segmentDir = resolveSegmentDir(appDir, node);
-      const searchParamsFile = findSearchParamsFile(segmentDir);
-      if (searchParamsFile) {
+    // Detect searchParams export from params.ts (primary) or page.tsx (fallback)
+    if (isPage) {
+      if (node.params && fileHasExport(node.params.filePath, 'searchParams')) {
         entry.hasSearchParams = true;
-        entry.searchParamsAbsPath = searchParamsFile;
+        entry.searchParamsPagePath = node.params.filePath;
+      } else if (node.page && fileHasExport(node.page.filePath, 'searchParams')) {
+        entry.hasSearchParams = true;
+        entry.searchParamsPagePath = node.page.filePath;
       }
     }
 
@@ -110,12 +115,12 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, appDir, routes);
+    collectRoutes(child, params, routes);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
   for (const [, slot] of node.slots) {
-    collectRoutes(slot, params, appDir, routes);
+    collectRoutes(slot, params, routes);
   }
 }
 
@@ -134,33 +139,43 @@ function paramTypeForSegment(segmentType: string): ParamEntry['type'] {
 }
 
 /**
- * Resolve the absolute directory path for a segment node.
+ * Check if a file exports a specific named export.
  *
- * Reconstructs the filesystem path by walking from appDir through
- * the segment names encoded in the urlPath, accounting for groups and slots.
+ * Uses a lightweight regex check — not full AST parsing. The actual type
+ * extraction happens via the TypeScript compiler in the generated .d.ts.
  */
-function resolveSegmentDir(appDir: string, node: SegmentNode): string {
-  // The node's page/route file path gives us the actual directory
-  const file = node.page ?? node.route;
-  if (file) {
-    // The file is in the segment directory — go up one level
-    const parts = file.filePath.split('/');
-    parts.pop(); // remove filename
-    return parts.join('/');
+function fileHasExport(filePath: string, exportName: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const e = exportName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return (
+      new RegExp(`export\\s+(const|let|var)\\s+${e}\\b`).test(content) ||
+      new RegExp(`export\\s*\\{[^}]*\\b${e}\\b[^}]*\\}`).test(content)
+    );
+  } catch {
+    return false;
   }
-  // Fallback: construct from urlPath (imprecise for groups, but acceptable)
-  return appDir;
 }
 
 /**
- * Find a search-params.ts file in a directory.
+ * Find which file exports `segmentParams` for a dynamic segment.
+ *
+ * Priority: params.ts (convention file) > layout > page.
+ * params.ts is the canonical location (TIM-508). Layout/page fallback
+ * exists for backward compat during migration.
  */
-function findSearchParamsFile(dirPath: string): string | undefined {
-  for (const ext of ['ts', 'tsx']) {
-    const candidate = join(dirPath, `search-params.${ext}`);
-    if (existsSync(candidate)) {
-      return candidate;
-    }
+function findParamsExport(node: SegmentNode): string | undefined {
+  // params.ts convention file — primary location
+  if (node.params && fileHasExport(node.params.filePath, 'segmentParams')) {
+    return node.params.filePath;
+  }
+  // Fallback: layout or page export (legacy, will be removed)
+  if (node.layout && fileHasExport(node.layout.filePath, 'segmentParams')) {
+    return node.layout.filePath;
+  }
+  if (node.page && fileHasExport(node.page.filePath, 'segmentParams')) {
+    return node.page.filePath;
   }
   return undefined;
 }
@@ -184,7 +199,7 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   lines.push('  interface Routes {');
 
   for (const route of routes) {
-    const paramsType = formatParamsType(route.params);
+    const paramsType = formatParamsType(route.params, importBase);
     const searchParamsType = formatSearchParamsType(route, importBase);
 
     lines.push(`    '${route.urlPath}': {`);
@@ -200,15 +215,9 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   // Generate @timber-js/app/server augmentation — typed searchParams() generic
   const pageRoutes = routes.filter((r) => !r.isApiRoute);
 
-  if (pageRoutes.length > 0) {
-    lines.push("declare module '@timber-js/app/server' {");
-    lines.push("  import type { Routes } from '@timber-js/app'");
-    lines.push(
-      "  export function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>"
-    );
-    lines.push('}');
-    lines.push('');
-  }
+  // Note: searchParams() always returns Promise<URLSearchParams>.
+  // Typed parsing is done via definition.parse(searchParams()).
+  // No module augmentation needed for @timber-js/app/server.
 
   // Generate overloads for @timber-js/app/client
   const dynamicRoutes = routes.filter((r) => r.params.length > 0);
@@ -223,10 +232,10 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
     // useParams overloads
     if (dynamicRoutes.length > 0) {
       for (const route of dynamicRoutes) {
-        const paramsType = formatParamsType(route.params);
-        lines.push(`  export function useParams(route: '${route.urlPath}'): ${paramsType}`);
+        const paramsType = formatParamsType(route.params, importBase);
+        lines.push(`  export function useSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
       }
-      lines.push('  export function useParams(): Record<string, string | string[]>');
+      lines.push('  export function useSegmentParams(): Record<string, string | string[]>');
       lines.push('');
     }
 
@@ -252,12 +261,27 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
 /**
  * Format the params type for a route entry.
  */
-function formatParamsType(params: ParamEntry[]): string {
+function formatParamsType(params: ParamEntry[], importBase?: string): string {
   if (params.length === 0) {
     return '{}';
   }
 
-  const fields = params.map((p) => `${p.name}: ${p.type}`);
+  const fields = params.map((p) => {
+    if (p.codecFilePath) {
+      // Use the codec's inferred type from the layout/page file
+      const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, '');
+      let importPath: string;
+      if (importBase) {
+        importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
+      } else {
+        importPath = './' + posix.basename(absPath);
+      }
+      // Extract T from the 'segmentParams' named export's ParamsDefinition<T>
+      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
+      return `${p.name}: ${codecType}`;
+    }
+    return `${p.name}: ${p.type}`;
+  });
   return `{ ${fields.join('; ')} }`;
 }
 
@@ -270,12 +294,24 @@ function formatParamsType(params: ParamEntry[]): string {
  *
  * See design/07-routing.md §"Typed params and searchParams on <Link>"
  */
-function formatLinkParamsType(params: ParamEntry[]): string {
+function formatLinkParamsType(params: ParamEntry[], importBase?: string): string {
   if (params.length === 0) {
     return '{}';
   }
 
   const fields = params.map((p) => {
+    if (p.codecFilePath) {
+      // With a codec, Link params use the codec's output type
+      const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, '');
+      let importPath: string;
+      if (importBase) {
+        importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
+      } else {
+        importPath = './' + posix.basename(absPath);
+      }
+      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
+      return `${p.name}: ${codecType}`;
+    }
     // Single dynamic segments accept string | number for convenience
     const type = p.type === 'string' ? 'string | number' : p.type;
     return `${p.name}: ${type}`;
@@ -286,13 +322,13 @@ function formatLinkParamsType(params: ParamEntry[]): string {
 /**
  * Format the searchParams type for a route entry.
  *
- * When a search-params.ts exists, we reference its inferred type via an import type.
+ * When a page.tsx exports searchParams, we reference its inferred type via an import type.
  * The import path is relative to `importBase` (the directory where the .d.ts will be
  * written). When importBase is undefined, falls back to a bare relative path.
  */
 function formatSearchParamsType(route: RouteEntry, importBase?: string): string {
-  if (route.hasSearchParams && route.searchParamsAbsPath) {
-    const absPath = route.searchParamsAbsPath.replace(/\.(ts|tsx)$/, '');
+  if (route.hasSearchParams && route.searchParamsPagePath) {
+    const absPath = route.searchParamsPagePath.replace(/\.(ts|tsx)$/, '');
     let importPath: string;
     if (importBase) {
       // Make the path relative to the output directory, converted to posix separators
@@ -300,10 +336,8 @@ function formatSearchParamsType(route: RouteEntry, importBase?: string): string
     } else {
       importPath = './' + posix.basename(absPath);
     }
-    // Use (typeof import('...'))[' default'] instead of import('...').default
-    // because with moduleResolution:"bundler", import('...').default is treated as
-    // a namespace member access which doesn't work for default exports.
-    return `(typeof import('${importPath}'))['default'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
+    // Extract the type from the named 'searchParams' export of the page module.
+    return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
   }
   return '{}';
 }
@@ -353,38 +387,25 @@ function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): st
 
   for (const route of routes) {
     const hasDynamicParams = route.params.length > 0;
-    const paramsType = formatLinkParamsType(route.params);
+    const paramsProp = hasDynamicParams
+      ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}`
+      : 'segmentParams?: never';
+
     const searchParamsType = route.hasSearchParams
       ? formatSearchParamsType(route, importBase)
       : null;
+    const searchParamsProp = searchParamsType
+      ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
+      : 'searchParams?: never';
 
-    if (hasDynamicParams) {
-      // Route with dynamic segments — params prop required
-      const spProp = searchParamsType
-        ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-        : `searchParams?: never`;
-      lines.push(
-        `  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`
-      );
-      lines.push(`    href: '${route.urlPath}'`);
-      lines.push(`    params: ${paramsType}`);
-      lines.push(`    ${spProp}`);
-      lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);
-      lines.push(`  }): import('react').JSX.Element`);
-    } else {
-      // Static route — no params needed
-      const spProp = searchParamsType
-        ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-        : `searchParams?: never`;
-      lines.push(
-        `  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`
-      );
-      lines.push(`    href: '${route.urlPath}'`);
-      lines.push(`    params?: never`);
-      lines.push(`    ${spProp}`);
-      lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);
-      lines.push(`  }): import('react').JSX.Element`);
-    }
+    lines.push(
+      `  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`
+    );
+    lines.push(`    href: '${route.urlPath}'`);
+    lines.push(`    ${paramsProp}`);
+    lines.push(`    ${searchParamsProp}`);
+    lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);
+    lines.push(`  }): import('react').JSX.Element`);
   }
 
   // Fallback overload for arbitrary string hrefs (escape hatch)

package/src/routing/scanner.ts

@@ -53,7 +53,7 @@ const LEGACY_STATUS_FILES: Record<string, number> = {
 /**
  * File convention names that are always .ts/.tsx (never .mdx etc.)
  */
-const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'prerender', 'search-params']);
+const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'params']);
 
 /**
  * Status-code file patterns:
@@ -92,6 +92,10 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
   // Validate: detect route group collisions (different groups producing pages at the same URL)
   validateRouteGroupCollisions(tree.root);
 
+  // Validate: detect duplicate param names in nested dynamic segments
+  // e.g., /[id]/items/[id] — same param name in ancestor and descendant
+  validateDuplicateParamNames(tree.root);
+
   return tree;
 }
 
@@ -278,11 +282,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
         case 'route':
           node.route = file;
           break;
-        case 'prerender':
-          node.prerender = file;
-          break;
-        case 'search-params':
-          node.searchParams = file;
+        case 'params':
+          node.params = file;
           break;
       }
       continue;
@@ -482,6 +483,54 @@ function collectRoutableLeaves(
   }
 }
 
+/**
+ * Validate that no route chain contains duplicate dynamic param names.
+ *
+ * Example violation:
+ *   app/[id]/items/[id]/page.tsx — 'id' appears twice in the ancestor chain.
+ *
+ * Route groups are transparent — params accumulate through them.
+ * Slots are independent — duplicate detection does NOT cross slot boundaries.
+ *
+ * See design/07-routing.md §"Duplicate Param Name Detection"
+ */
+function validateDuplicateParamNames(root: SegmentNode): void {
+  walkForDuplicateParams(root, new Map());
+}
+
+/**
+ * Recursively walk the segment tree, tracking seen param names → segment paths.
+ * Throws on the first duplicate found.
+ */
+function walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): void {
+  // If this node introduces a param name, check for duplicates
+  if (node.paramName) {
+    const existing = seen.get(node.paramName);
+    if (existing) {
+      throw new Error(
+        `[timber] Duplicate param name '${node.paramName}' in route chain.\n` +
+          `  First defined at: ${existing}\n` +
+          `  Duplicate at: ${node.urlPath || '/'}\n` +
+          `  Rename one of the segments to avoid ambiguity.`
+      );
+    }
+    // Add to seen for descendants (use a new Map to avoid polluting siblings)
+    seen = new Map(seen);
+    seen.set(node.paramName, node.urlPath || '/');
+  }
+
+  // Recurse into children (they inherit the accumulated params)
+  for (const child of node.children) {
+    walkForDuplicateParams(child, seen);
+  }
+
+  // Slots are independent parallel routes — start fresh param tracking
+  // (a slot's params don't conflict with the main route's params)
+  for (const [, slotNode] of node.slots) {
+    walkForDuplicateParams(slotNode, new Map(seen));
+  }
+}
+
 /**
  * Find a fixed-extension file (proxy.ts) in a directory.
  */

package/src/routing/status-file-lint.ts

@@ -31,7 +31,8 @@ export interface StatusFileLintWarning {
  * that are missing it.
  *
  * MDX and JSON status files are excluded — MDX files are server components
- * by design, and JSON files are data, not components.
+ * by design (pre-rendered as elements via fallbackElement, see TIM-503),
+ * and JSON files are data, not components.
  */
 export function lintStatusFileDirectives(tree: RouteTree): StatusFileLintWarning[] {
   const warnings: StatusFileLintWarning[] = [];

package/src/routing/types.ts

@@ -59,6 +59,12 @@ export interface SegmentNode {
   middleware?: RouteFile;
   access?: RouteFile;
   route?: RouteFile;
+  /**
+   * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.
+   * Discovered by the scanner like middleware.ts and access.ts.
+   * See design/07-routing.md §"params.ts Convention File"
+   */
+  params?: RouteFile;
   error?: RouteFile;
   default?: RouteFile;
   /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */
@@ -69,10 +75,7 @@ export interface SegmentNode {
   denied?: RouteFile;
   /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
   legacyStatusFiles?: Map<string, RouteFile>;
-  /** prerender.ts — signals build-time pre-rendering for this segment's shell */
-  prerender?: RouteFile;
-  /** search-params.ts — typed search params definition for this route */
-  searchParams?: RouteFile;
+
   /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
   metadataRoutes?: Map<string, RouteFile>;
 

package/src/rsc-runtime/rsc.ts

@@ -16,4 +16,6 @@ export {
   loadServerAction,
   decodeReply,
   decodeAction,
+  encryptActionBoundArgs,
+  decryptActionBoundArgs,
 } from '@vitejs/plugin-rsc/rsc';

package/src/rsc-runtime/ssr.ts

@@ -11,3 +11,53 @@
  */
 
 export { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';
+
+// ─── Node.js Stream Path ─────────────────────────────────────────────────────
+//
+// On Node.js, createFromNodeStream reads RSC Flight data from a Node.js
+// Readable (C++ backed) instead of a Web ReadableStream (JS reimplementation).
+// Eliminates Promise-per-chunk overhead on the SSR decode path.
+//
+// The plugin only exports createFromReadableStream (via client.edge.js).
+// createFromNodeStream lives in the vendored client.node.js. We import it
+// directly and wire up the same serverConsumerManifest the plugin uses.
+
+import { createServerConsumerManifest } from '@vitejs/plugin-rsc/ssr';
+
+type CreateFromNodeStreamFn = (
+  stream: import('node:stream').Readable,
+  manifest: ReturnType<typeof createServerConsumerManifest>,
+  options?: Record<string, unknown>
+) => React.ReactNode;
+
+let _createFromNodeStream: CreateFromNodeStreamFn | null = null;
+
+try {
+  if (typeof process !== 'undefined' && process.release?.name === 'node') {
+    const clientNode = await import('@vitejs/plugin-rsc/vendor/react-server-dom/client.node');
+    if (typeof clientNode.createFromNodeStream === 'function') {
+      _createFromNodeStream = clientNode.createFromNodeStream;
+    }
+  }
+} catch {
+  // Not available — fall back to createFromReadableStream
+}
+
+/**
+ * Decode an RSC Flight stream from a Node.js Readable.
+ *
+ * Uses the vendored createFromNodeStream which reads via Node.js native
+ * streams (C++ libuv) instead of Web ReadableStream (JS Promise per chunk).
+ *
+ * Returns null if createFromNodeStream isn't available (CF Workers, etc),
+ * signaling the caller to use createFromReadableStream instead.
+ */
+export function createFromNodeStream(
+  stream: import('node:stream').Readable
+): React.ReactNode | null {
+  if (!_createFromNodeStream) return null;
+  return _createFromNodeStream(stream, createServerConsumerManifest());
+}
+
+/** Whether the Node.js stream RSC decode path is available. */
+export const hasNodeStreamDecode = _createFromNodeStream !== null;

package/src/rsc-runtime/vendor-types.d.ts

@@ -0,0 +1,7 @@
+declare module '@vitejs/plugin-rsc/vendor/react-server-dom/client.node' {
+  export function createFromNodeStream(
+    stream: import('node:stream').Readable,
+    manifest: unknown,
+    options?: Record<string, unknown>
+  ): React.ReactNode;
+}

package/src/search-params/codecs.ts

@@ -5,7 +5,7 @@
  * Design doc: design/09-typescript.md §"The SearchParamCodec Protocol"
  */
 
-import type { SearchParamCodec } from './create.js';
+import type { SearchParamCodec } from './define.js';
 
 // ---------------------------------------------------------------------------
 // Standard Schema interface (subset)