@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/src/routing/scanner.ts

@@ -18,8 +18,9 @@ import type {
   ScannerConfig,
   InterceptionMarker,
 } from './types.js';
+import { classifyUrlSegment } from './segment-classify.js';
 import { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-import { classifyMetadataRoute, isDynamicMetadataExtension } from '#/server/metadata-routes.js';
+import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';
 
 /**
  * Pattern matching encoded path delimiters that must be rejected during route discovery.
@@ -53,7 +54,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:
@@ -83,6 +84,14 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
     tree.proxy = proxyFile;
   }
 
+  // Check for global-error.{tsx,ts,jsx,js} at app root.
+  // Tier 2 error page — renders standalone (no layouts) when no segment-level
+  // error file is found. See design/10-error-handling.md §"Tier 2".
+  const globalErrorFile = findPageExtFile(appDir, 'global-error', extSet);
+  if (globalErrorFile) {
+    tree.globalError = globalErrorFile;
+  }
+
   // Scan the root directory's files
   scanSegmentFiles(appDir, tree.root, extSet);
 
@@ -92,6 +101,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;
 }
 
@@ -153,22 +166,12 @@ export function classifySegment(dirName: string): {
     return { type: 'group' };
   }
 
-  // Optional catch-all: [[...name]]
-  if (dirName.startsWith('[[...') && dirName.endsWith(']]')) {
-    const paramName = dirName.slice(5, -2);
-    return { type: 'optional-catch-all', paramName };
-  }
-
-  // Catch-all: [...name]
-  if (dirName.startsWith('[...') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(4, -1);
-    return { type: 'catch-all', paramName };
-  }
-
-  // Dynamic: [name]
-  if (dirName.startsWith('[') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(1, -1);
-    return { type: 'dynamic', paramName };
+  // Bracket-syntax segments: [param], [...param], [[...param]]
+  // Delegated to the shared character-based classifier. If you change
+  // bracket syntax, update segment-classify.ts — not here.
+  const urlSeg = classifyUrlSegment(dirName);
+  if (urlSeg.kind !== 'static') {
+    return { type: urlSeg.kind, paramName: urlSeg.name };
   }
 
   return { type: 'static' };
@@ -278,11 +281,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 +482,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.
  */
@@ -498,3 +546,25 @@ function findFixedFile(dirPath: string, name: string): RouteFile | undefined {
   }
   return undefined;
 }
+
+/**
+ * Find a file using the configured page extensions (tsx, ts, jsx, js, mdx, etc.).
+ * Used for app-root conventions like global-error that aren't per-segment.
+ */
+function findPageExtFile(
+  dirPath: string,
+  name: string,
+  extSet: Set<string>
+): RouteFile | undefined {
+  for (const ext of extSet) {
+    const fullPath = join(dirPath, `${name}.${ext}`);
+    try {
+      if (statSync(fullPath).isFile()) {
+        return { filePath: fullPath, extension: ext };
+      }
+    } catch {
+      // File doesn't exist
+    }
+  }
+  return undefined;
+}

package/src/routing/segment-classify.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared URL segment classifier.
+ *
+ * Single-pass character parser that classifies a route segment token
+ * (e.g. "dashboard", "[id]", "[...slug]", "[[...path]]") into a typed
+ * discriminated union. Used by both server-side routing and client-side
+ * Link interpolation.
+ *
+ * NO regex. NO Node.js-only APIs. Safe to import from browser code.
+ *
+ * Malformed input (unclosed brackets, empty names, etc.) falls through
+ * to { kind: 'static' } — the safe default.
+ *
+ * If you change the bracket syntax, update ONLY this file. Every
+ * consumer imports from here.
+ *
+ * See design/07-routing.md §"Route Segments"
+ */
+
+export type UrlSegment =
+  | { kind: 'static'; value: string }
+  | { kind: 'dynamic'; name: string }
+  | { kind: 'catch-all'; name: string }
+  | { kind: 'optional-catch-all'; name: string };
+
+/**
+ * Classify a URL path segment token.
+ *
+ * Walks the string left-to-right in one pass:
+ *   1. If it doesn't start with '[', it's static.
+ *   2. Count opening brackets (1 or 2) to detect optional.
+ *   3. Check for '...' to detect catch-all.
+ *   4. Read the param name up to the closing bracket.
+ *   5. Validate the expected closing sequence (']' or ']]').
+ *   6. Reject if there are leftover characters after the close.
+ *
+ * Any structural violation → static (safe default).
+ */
+export function classifyUrlSegment(token: string): UrlSegment {
+  const len = token.length;
+
+  // Must start with '[' to be dynamic
+  if (len === 0 || token[0] !== '[') {
+    return { kind: 'static', value: token };
+  }
+
+  let i = 1;
+
+  // Check for optional: '[[...'
+  const optional = token[i] === '[';
+  if (optional) i++;
+
+  // Check for catch-all: '...'
+  const catchAll = i + 2 < len && token[i] === '.' && token[i + 1] === '.' && token[i + 2] === '.';
+  if (catchAll) i += 3;
+
+  // Read param name — everything up to ']'
+  const nameStart = i;
+  while (i < len && token[i] !== ']') i++;
+
+  // Must have found a ']' and name must be non-empty
+  if (i >= len || i === nameStart) {
+    return { kind: 'static', value: token };
+  }
+
+  const name = token.slice(nameStart, i);
+  i++; // skip first ']'
+
+  // Optional requires a second ']'
+  if (optional) {
+    if (i >= len || token[i] !== ']') {
+      return { kind: 'static', value: token };
+    }
+    i++;
+  }
+
+  // Must be at end of string — no trailing characters
+  if (i !== len) {
+    return { kind: 'static', value: token };
+  }
+
+  if (optional && catchAll) return { kind: 'optional-catch-all', name };
+  if (catchAll) return { kind: 'catch-all', name };
+  if (optional) {
+    // '[[name]]' without '...' is malformed — not a valid segment syntax
+    return { kind: 'static', value: token };
+  }
+  return { kind: 'dynamic', name };
+}

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

@@ -15,7 +15,7 @@
 
 import { readFileSync } from 'node:fs';
 import type { RouteTree, SegmentNode } from './types.js';
-import { detectFileDirective } from '#/utils/directive-parser.js';
+import { detectFileDirective } from '../utils/directive-parser.js';
 
 /** Extensions that require 'use client' (component files, not MDX/JSON). */
 const CLIENT_REQUIRED_EXTENSIONS = new Set(['tsx', 'jsx', 'ts', 'js']);
@@ -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>;
 
@@ -88,6 +91,16 @@ export interface RouteTree {
   root: SegmentNode;
   /** All discovered proxy.ts files (should be at most one, in app/) */
   proxy?: RouteFile;
+  /**
+   * Global error page: app/global-error.{tsx,ts,jsx,js}
+   *
+   * Rendered as a standalone full-page replacement (no layout wrapping)
+   * when no segment-level error file is found. SSR-only render path.
+   * Must provide its own <html> and <body>.
+   *
+   * See design/10-error-handling.md §"Tier 2 — Global Error Page"
+   */
+  globalError?: RouteFile;
 }
 
 /** Configuration passed to the scanner */

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 → schema-bridge.ts}

@@ -1,11 +1,21 @@
 /**
- * Built-in codecs and the fromSchema bridge for Standard Schema-compatible
- * validation libraries (Zod, Valibot, ArkType).
+ * Standard Schema bridge — shared helpers for bridging Standard Schema-compatible
+ * validation libraries (Zod, Valibot, ArkType) to the Codec<T> protocol.
  *
- * Design doc: design/09-typescript.md §"The SearchParamCodec Protocol"
+ * This module is the single source of truth for:
+ * - StandardSchemaV1 interface (subset of the Standard Schema spec)
+ * - validateSync() helper
+ * - fromSchema() — bridge from Standard Schema to Codec<T>
+ * - fromArraySchema() — bridge for array-valued codecs
+ *
+ * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,
+ * and @timber-js/app/cookies for convenience. The canonical import is
+ * @timber-js/app/codec.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
  */
 
-import type { SearchParamCodec } from './create.js';
+import type { Codec } from './codec.js';
 
 // ---------------------------------------------------------------------------
 // Standard Schema interface (subset)
@@ -15,13 +25,14 @@ import type { SearchParamCodec } from './create.js';
 // We depend only on `~standard.validate` to avoid coupling to any specific lib.
 // ---------------------------------------------------------------------------
 
-interface StandardSchemaV1<Output = unknown> {
+/** Minimal Standard Schema interface for auto-detection. */
+export interface StandardSchemaV1<Output = unknown> {
   '~standard': {
     validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
   };
 }
 
-type StandardSchemaResult<Output> =
+export type StandardSchemaResult<Output> =
   | { value: Output; issues?: undefined }
   | { value?: undefined; issues: ReadonlyArray<{ message: string }> };
 
@@ -30,46 +41,72 @@ type StandardSchemaResult<Output> =
 // ---------------------------------------------------------------------------
 
 /**
- * Zod v4's ~standard.validate() signature includes Promise in the return union
- * to satisfy the Standard Schema spec, but in practice Zod always validates
- * synchronously for the schema types we use. We assert the result is sync and
- * throw if it isn't — search params parsing must be synchronous.
+ * Run a Standard Schema's `~standard.validate()` synchronously.
+ *
+ * Zod v4's signature includes `Promise` in the return union to satisfy the
+ * Standard Schema spec, but in practice Zod always validates synchronously
+ * for the schema types we use. We assert the result is sync and throw if
+ * it isn't — codec parsing must be synchronous.
  */
-function validateSync<Output>(
+export function validateSync<Output>(
   schema: StandardSchemaV1<Output>,
   value: unknown
 ): StandardSchemaResult<Output> {
   const result = schema['~standard'].validate(value);
   if (result instanceof Promise) {
     throw new Error(
-      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'
+      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported.'
     );
   }
   return result;
 }
 
 // ---------------------------------------------------------------------------
-// fromSchema — bridge from Standard Schema to SearchParamCodec
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Check if a value is a Standard Schema object. */
+export function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '~standard' in value &&
+    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'
+  );
+}
+
+/** Check if a value is a Codec (has parse + serialize methods). */
+export function isCodec(value: unknown): value is Codec<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Codec<unknown>).parse === 'function' &&
+    typeof (value as Codec<unknown>).serialize === 'function'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// fromSchema — bridge from Standard Schema to Codec<T>
 // ---------------------------------------------------------------------------
 
 /**
  * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
- * SearchParamCodec.
+ * Codec<T>.
  *
- * Parse: coerces the raw URL string through the schema. On validation failure,
+ * Parse: coerces the raw string through the schema. On validation failure,
  * parses `undefined` to get the schema's default value (the schema should have
  * a `.default()` call). If that also fails, returns `undefined`.
  *
  * Serialize: uses `String()` for primitives, `null` for null/undefined.
  *
  * ```ts
- * import { fromSchema } from '@timber-js/app/search-params'
+ * import { fromSchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
  * ```
  */
-export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
     parse(value: string | string[] | undefined): T {
       // For array inputs, take the last value (consistent with URLSearchParams.get())
@@ -101,7 +138,7 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T>
 }
 
 // ---------------------------------------------------------------------------
-// fromArraySchema — bridge for array-valued search params
+// fromArraySchema — bridge for array-valued codecs
 // ---------------------------------------------------------------------------
 
 /**
@@ -109,13 +146,13 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T>
  * and repeated query keys (`?tag=a&tag=b`).
  *
  * ```ts
- * import { fromArraySchema } from '@timber-js/app/search-params'
+ * import { fromArraySchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
  * ```
  */
-export function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+export function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
     parse(value: string | string[] | undefined): T {
       // Coerce single string to array for array schemas