@timber-js/app 0.2.0-alpha.110 → 0.2.0-alpha.112

package/src/routing/codegen.ts

@@ -9,10 +9,12 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import type { RouteTree, SegmentNode } from './types.js';
 import type { ParamEntry, RouteEntry } from './codegen-types.js';
 import {
   buildCodecChainType,
+  buildSchemaParamType,
   emitResolveSegmentFieldHelper,
   formatSearchParamsType,
 } from './codegen-shared.js';
@@ -28,6 +30,11 @@ export interface CodegenOptions {
    * Defaults to appDir when not provided (preserves backward compat for tests).
    */
   outputDir?: string;
+  /**
+   * Whether a global schema (app/schema.ts) exists.
+   * Auto-detected from appDir when not explicitly set.
+   */
+  hasSchema?: boolean;
 }
 
 /**
@@ -37,8 +44,11 @@ export interface CodegenOptions {
  * interface that maps every route path to its params and searchParams shape.
  */
 export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {
+  // Auto-detect schema from appDir when not explicitly set
+  const hasSchema = options.hasSchema ?? detectSchema(options.appDir);
+
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], [], routes);
+  collectRoutes(tree.root, [], [], routes, hasSchema);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -46,7 +56,18 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
   // When outputDir differs from appDir, import paths must be relative to outputDir
   const importBase = options.outputDir ?? options.appDir;
 
-  return formatDeclarationFile(routes, importBase);
+  return formatDeclarationFile(routes, importBase, hasSchema);
+}
+
+/** Schema file extensions to check, in priority order. */
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * Detect whether app/schema.{ts,tsx,js,jsx} exists.
+ */
+function detectSchema(appDir: string | undefined): boolean {
+  if (!appDir) return false;
+  return SCHEMA_EXTENSIONS.some((ext) => existsSync(join(appDir, `schema${ext}`)));
 }
 
 /**
@@ -59,7 +80,8 @@ function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
   ancestorParamsFiles: string[],
-  routes: RouteEntry[]
+  routes: RouteEntry[],
+  hasSchema: boolean
 ): void {
   // TIM-834: Identify this segment's own params.ts (if it has a
   // segmentParams export). The full chain of params.ts files in the
@@ -83,6 +105,7 @@ function collectRoutes(
     const legacyFallback = ownParamsFile ? undefined : findLegacyParamsExport(node);
     params.push({
       name: node.paramName,
+      bracketName: node.segmentName,
       type: paramTypeForSegment(node.segmentType),
       // Codec chain populated at leaf time. We carry the per-segment
       // legacy fallback (if any) so leaf-time resolution can fall back
@@ -117,6 +140,7 @@ function collectRoutes(
             : undefined;
       return {
         name: p.name,
+        bracketName: p.bracketName,
         type: p.type,
         codecFilePaths,
       };
@@ -127,6 +151,7 @@ function collectRoutes(
       params: resolvedParams,
       hasSearchParams: false,
       isApiRoute,
+      hasSchema,
     };
 
     // Detect searchParams export from params.ts (primary) or page.tsx (fallback)
@@ -145,12 +170,12 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, nextAncestorFiles, routes);
+    collectRoutes(child, params, nextAncestorFiles, routes, hasSchema);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
   for (const slot of Object.values(node.slots)) {
-    collectRoutes(slot, params, nextAncestorFiles, routes);
+    collectRoutes(slot, params, nextAncestorFiles, routes, hasSchema);
   }
 }
 
@@ -205,10 +230,71 @@ function findLegacyParamsExport(node: SegmentNode): string | undefined {
   return undefined;
 }
 
+/**
+ * Emit the schema-based type exports: TimberSegmentParams, TimberRoute,
+ * AllSegmentParams, RoutesWithParams.
+ *
+ * These types use InferCodecType references so they stay in sync with
+ * the schema without hardcoding resolved types.
+ *
+ * Design doc: design/41-global-params.md §Codegen Output
+ */
+function formatSchemaTypes(routes: RouteEntry[]): string[] {
+  const lines: string[] = [];
+
+  lines.push('/** Union of all valid route patterns. */');
+  lines.push('export type TimberRoute = keyof TimberSegmentParams;');
+  lines.push('');
+  lines.push('/** Maps each route pattern to its accumulated segment params. */');
+  lines.push('export interface TimberSegmentParams {');
+
+  for (const route of routes) {
+    if (route.params.length === 0) {
+      lines.push(`  '${route.urlPath}': {};`);
+    } else {
+      lines.push(`  '${route.urlPath}': {`);
+      for (const p of route.params) {
+        lines.push(`    ${p.name}: ${buildSchemaParamType(p)};`);
+      }
+      lines.push('  };');
+    }
+  }
+
+  lines.push('}');
+  lines.push('');
+
+  // AllSegmentParams — flat union of all param types across all routes
+  lines.push('/** All segment params (union of all route params). */');
+  lines.push('export type AllSegmentParams = {');
+  lines.push(
+    '  [K in keyof TimberSegmentParams as TimberSegmentParams[K] extends Record<string, never>'
+  );
+  lines.push('    ? never');
+  lines.push('    : K]: TimberSegmentParams[K];');
+  lines.push('} extends infer U');
+  lines.push('  ? { [K in keyof U[keyof U]]: U[keyof U][K] }');
+  lines.push('  : never;');
+  lines.push('');
+
+  // RoutesWithParams — filter routes by required param keys
+  lines.push(
+    '/** Filters TimberRoute to routes whose accumulated params include all listed keys. */'
+  );
+  lines.push('export type RoutesWithParams<K extends keyof AllSegmentParams> = {');
+  lines.push('  [R in TimberRoute]: K extends keyof TimberSegmentParams[R] ? R : never;');
+  lines.push('}[TimberRoute];');
+
+  return lines;
+}
+
 /**
  * Format the collected routes into a TypeScript declaration file.
  */
-function formatDeclarationFile(routes: RouteEntry[], importBase?: string): string {
+function formatDeclarationFile(
+  routes: RouteEntry[],
+  importBase?: string,
+  hasSchema?: boolean
+): string {
   const lines: string[] = [];
 
   lines.push('// This file is auto-generated by timber.js route map codegen.');
@@ -221,16 +307,29 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   lines.push('export {};');
   lines.push('');
 
-  // TIM-834 P2: emit the shared codec-resolution helper type ONCE so the
-  // per-param chain conditionals reference it instead of inlining the
-  // fallback in both branches (which grows O(2^N) in chain depth).
-  lines.push(emitResolveSegmentFieldHelper());
-  lines.push('');
+  if (hasSchema) {
+    // Schema-based codegen: import schema and InferCodecType
+    lines.push("import type schema from '../app/schema';");
+    lines.push("import type { InferCodecType } from '@timber-js/app/params';");
+    lines.push('');
+    // Emit TimberSegmentParams, TimberRoute, AllSegmentParams, RoutesWithParams
+    lines.push(...formatSchemaTypes(routes));
+    lines.push('');
+  }
+
+  if (!hasSchema) {
+    // TIM-834 P2: emit the shared codec-resolution helper type ONCE so the
+    // per-param chain conditionals reference it instead of inlining the
+    // fallback in both branches (which grows O(2^N) in chain depth).
+    lines.push(emitResolveSegmentFieldHelper());
+    lines.push('');
+  }
+
   lines.push("declare module '@timber-js/app' {");
   lines.push('  interface Routes {');
 
   for (const route of routes) {
-    const paramsType = formatParamsType(route.params, importBase);
+    const paramsType = formatParamsType(route.params, importBase, hasSchema);
     const searchParamsType = formatSearchParamsType(route, importBase);
 
     lines.push(`    '${route.urlPath}': {`);
@@ -243,15 +342,22 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   lines.push('}');
   lines.push('');
 
-  // Generate @timber-js/app/server augmentation — typed searchParams() generic
   const pageRoutes = routes.filter((r) => !r.isApiRoute);
+  const dynamicRoutes = routes.filter((r) => r.params.length > 0);
 
-  // Note: searchParams() always returns Promise<URLSearchParams>.
-  // Typed parsing is done via definition.parse(searchParams()).
-  // No module augmentation needed for @timber-js/app/server.
+  // Generate @timber-js/app/server augmentation — typed getSegmentParams
+  if (dynamicRoutes.length > 0) {
+    lines.push("declare module '@timber-js/app/server' {");
+    for (const route of dynamicRoutes) {
+      const paramsType = formatParamsType(route.params, importBase, hasSchema);
+      lines.push(`  export function getSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
+    }
+    lines.push('  export function getSegmentParams(): Record<string, string | string[]>');
+    lines.push('}');
+    lines.push('');
+  }
 
   // Generate overloads for @timber-js/app/client
-  const dynamicRoutes = routes.filter((r) => r.params.length > 0);
 
   if (dynamicRoutes.length > 0 || pageRoutes.length > 0) {
     lines.push("declare module '@timber-js/app/client' {");
@@ -263,7 +369,7 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
     // useParams overloads
     if (dynamicRoutes.length > 0) {
       for (const route of dynamicRoutes) {
-        const paramsType = formatParamsType(route.params, importBase);
+        const paramsType = formatParamsType(route.params, importBase, hasSchema);
         lines.push(`  export function useSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
       }
       lines.push('  export function useSegmentParams(): Record<string, string | string[]>');
@@ -290,7 +396,7 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
     // confusing "Type 'string' is not assignable to type 'never'" cascade.
     if (pageRoutes.length > 0) {
       lines.push('  // Typed Link overloads — per-route (block 1 / emitted first)');
-      lines.push(...formatTypedLinkOverloads(pageRoutes, importBase));
+      lines.push(...formatTypedLinkOverloads(pageRoutes, importBase, hasSchema));
       lines.push('');
     }
 
@@ -315,13 +421,15 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
 /**
  * Format the params type for a route entry.
  */
-function formatParamsType(params: ParamEntry[], importBase?: string): string {
+function formatParamsType(params: ParamEntry[], importBase?: string, hasSchema?: boolean): string {
   if (params.length === 0) {
     return '{}';
   }
 
   const fields = params.map((p) => {
-    const codecType = buildCodecChainType(p, importBase, p.type);
+    const codecType = hasSchema
+      ? buildSchemaParamType(p)
+      : buildCodecChainType(p, importBase, p.type);
     return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;

package/src/routing/link-codegen.ts

@@ -24,7 +24,11 @@
  */
 
 import type { ParamEntry, RouteEntry } from './codegen-types.js';
-import { buildCodecChainType, formatSearchParamsType } from './codegen-shared.js';
+import {
+  buildCodecChainType,
+  buildSchemaParamType,
+  formatSearchParamsType,
+} from './codegen-shared.js';
 
 /** Shared Link base-props type literal used in every emitted call signature. */
 export const LINK_BASE_PROPS_TYPE =
@@ -67,14 +71,20 @@ export function buildResolvedPattern(route: RouteEntry): string | null {
  * When the segment's params chain (TIM-834) declares a typed codec, the
  * inferred type from the codec wins via a nested conditional.
  */
-export function formatLinkParamsType(params: ParamEntry[], importBase?: string): string {
+export function formatLinkParamsType(
+  params: ParamEntry[],
+  importBase?: string,
+  hasSchema?: boolean
+): string {
   if (params.length === 0) {
     return '{}';
   }
 
   const fields = params.map((p) => {
     const fallback = p.type === 'string' ? 'string | number' : p.type;
-    const codecType = buildCodecChainType(p, importBase, fallback);
+    const codecType = hasSchema
+      ? buildSchemaParamType(p)
+      : buildCodecChainType(p, importBase, fallback);
     return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;
@@ -192,7 +202,11 @@ export function formatLinkCatchAllOverloads(): string[] {
  * so the resolved-template-vs-pattern ordering reduces to placing the
  * pattern variant before the resolved-template variant inside the union.
  */
-export function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {
+export function formatTypedLinkOverloads(
+  routes: RouteEntry[],
+  importBase?: string,
+  hasSchema?: boolean
+): string[] {
   const lines: string[] = [];
   const baseProps = LINK_BASE_PROPS_TYPE;
 
@@ -215,7 +229,7 @@ export function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: stri
     // segmentParams. `Record<string, unknown>` keeps generic spreads
     // compiling and gives a readable error if a non-object is passed.
     const paramsProp = hasDynamicParams
-      ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}`
+      ? `segmentParams: ${formatLinkParamsType(route.params, importBase, hasSchema)}`
       : 'segmentParams?: Record<string, unknown>';
 
     const searchParamsType = route.hasSearchParams

package/src/server/als-registry.ts

@@ -59,6 +59,13 @@ export interface RequestContextStore {
    * See design/07-routing.md §"params.ts — Convention File for Typed Params"
    */
   segmentParams?: Record<string, string | string[]>;
+  /**
+   * The matched route pattern (e.g. '/[artistSlug]/[year]').
+   * Set by the pipeline alongside segmentParams. Used by
+   * getSegmentParams() for dev-mode route mismatch validation.
+   * See design/41-global-params.md §Runtime Validation
+   */
+  matchedRoutePattern?: string;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */

package/src/server/coalesce-tick.ts

@@ -0,0 +1,75 @@
+/**
+ * Single-shot `setImmediate` coalescing primitive.
+ *
+ * Multiple synchronous `schedule()` calls within one event-loop tick
+ * result in exactly one `flush` invocation at the end of that tick.
+ * No recursive scheduling, no busy-wait, no polling loop.
+ *
+ * Both `createBufferedTransformStream` (Web) and
+ * `createNodeBufferedTransform` (Node) use this helper so the invariant
+ * — and this comment — live in one place.
+ *
+ * **Not a polling loop.** Uses a single-shot `setImmediate` per flush
+ * cycle — no recursive scheduling, no busy-wait. See design/02
+ * §"No Polling".
+ */
+
+export interface TickCoalescer {
+  /**
+   * Request a flush at the end of the current tick. If a flush is already
+   * scheduled, this is a no-op. Returns the pending promise (or undefined
+   * if the flush already fired and no new one has been scheduled).
+   */
+  schedule(): void;
+
+  /**
+   * The pending flush promise, if any. Callers (e.g. `flush()` in a
+   * TransformStream) can `await` this to wait for the scheduled flush
+   * to complete before closing the stream.
+   */
+  readonly pending: Promise<void> | undefined;
+
+  /**
+   * Cancel any pending scheduled flush and invoke the flush callback
+   * synchronously. Used by Node `Transform.flush()` which needs to
+   * drain the buffer immediately before calling back.
+   */
+  flushSync(): void;
+}
+
+/**
+ * Create a tick coalescer that calls `onFlush` at most once per tick.
+ */
+export function createTickCoalescer(onFlush: () => void): TickCoalescer {
+  let pending: Promise<void> | undefined;
+  let immediateHandle: ReturnType<typeof setImmediate> | null = null;
+
+  function doFlush(): void {
+    immediateHandle = null;
+    pending = undefined;
+    onFlush();
+  }
+
+  return {
+    schedule() {
+      if (immediateHandle !== null) return;
+      pending = new Promise<void>((resolve) => {
+        immediateHandle = setImmediate(() => {
+          doFlush();
+          resolve();
+        });
+      });
+    },
+
+    get pending() {
+      return pending;
+    },
+
+    flushSync() {
+      if (immediateHandle !== null) {
+        clearImmediate(immediateHandle);
+        doFlush();
+      }
+    },
+  };
+}

package/src/server/fallback-error.ts

@@ -15,6 +15,7 @@ import type { ManifestSegmentNode } from './route-matcher.js';
 import type { ClientBootstrapConfig } from './html-injectors.js';
 import type { LayoutEntry } from './deny-renderer.js';
 import type { GlobalErrorFile } from './rsc-entry/error-renderer.js';
+import { swallow } from './logger.js';
 import { logRenderError } from './logger.js';
 import { loadModule } from './safe-load.js';
 import { sourceMapError } from './dev-source-map.js';
@@ -105,9 +106,8 @@ export async function renderDevErrorPage(error: unknown, projectRoot?: string):
       '</head>',
       '  <script type="module" src="/@vite/client"></script>\n</head>'
     );
-  } catch {
-    // If the shared template fails (e.g., circular dep, missing module),
-    // fall back to a minimal error page.
+  } catch (e) {
+    swallow(e, 'dev error page template failed, using minimal fallback');
     html = minimalErrorPage(err);
   }
 

package/src/server/html-injectors.ts

@@ -31,6 +31,7 @@ import {
 } from './html-injector-core.js';
 import { flightChunkScript } from './flight-scripts.js';
 import { withTimeout, RenderTimeoutError } from './render-timeout.js';
+import { createTickCoalescer } from './coalesce-tick.js';
 
 // ─── Buffered Transform ──────────────────────────────────────────────────────
 
@@ -58,11 +59,11 @@ export function createBufferedTransformStream(
   options: BufferedTransformOptions = {}
 ): TransformStream<Uint8Array, Uint8Array> {
   const buffer = new BufferAggregator(options.maxBufferByteLength ?? Infinity);
-  let pendingFlush: Promise<void> | undefined;
+  let controller: TransformStreamDefaultController<Uint8Array> | null = null;
 
-  const drainTo = (controller: TransformStreamDefaultController<Uint8Array>) => {
+  const drainTo = () => {
     const merged = buffer.drain();
-    if (!merged) return;
+    if (!merged || !controller) return;
     try {
       controller.enqueue(merged);
     } catch {
@@ -70,32 +71,20 @@ export function createBufferedTransformStream(
     }
   };
 
+  const coalescer = createTickCoalescer(drainTo);
+
   return new TransformStream<Uint8Array, Uint8Array>({
-    transform(chunk, controller) {
+    transform(chunk, ctrl) {
+      controller = ctrl;
       const overCap = buffer.append(chunk);
       if (overCap) {
-        // Buffer too large to hold — flush synchronously now.
-        drainTo(controller);
+        drainTo();
         return;
       }
-      if (pendingFlush) return;
-      // Single-shot setImmediate — fires once at the end of this tick,
-      // then the promise resolves. NOT a recursive loop. See design/02
-      // §"No Polling".
-      pendingFlush = new Promise<void>((resolve) => {
-        setImmediate(() => {
-          try {
-            drainTo(controller);
-          } finally {
-            pendingFlush = undefined;
-            resolve();
-          }
-        });
-      });
+      coalescer.schedule();
     },
     flush() {
-      // Wait for any pending scheduled flush to complete.
-      return pendingFlush;
+      return coalescer.pending;
     },
   });
 }

package/src/server/node-stream-transforms.ts

@@ -33,6 +33,7 @@ import {
   suffixFlush,
 } from './html-injector-core.js';
 import { logStreamingError } from './logger.js';
+import { createTickCoalescer } from './coalesce-tick.js';
 
 // ─── Buffered Transform ──────────────────────────────────────────────────────
 
@@ -58,37 +59,26 @@ export interface NodeBufferedTransformOptions {
  */
 export function createNodeBufferedTransform(options: NodeBufferedTransformOptions = {}): Transform {
   const buffer = new BufferAggregator(options.maxBufferByteLength ?? Infinity);
-  let pendingImmediate: ReturnType<typeof setImmediate> | null = null;
 
   const flushBuffer = () => {
     const merged = buffer.drain();
     if (merged) transform.push(merged);
   };
 
+  const coalescer = createTickCoalescer(flushBuffer);
+
   const transform = new Transform({
     transform(chunk: Buffer, _encoding, callback) {
       const overCap = buffer.append(chunk);
       if (overCap) {
-        // Buffer too large to hold — flush synchronously now.
         flushBuffer();
-      } else if (!pendingImmediate) {
-        // Schedule a deferred flush for end of this tick.
-        // Single-shot setImmediate — NOT a recursive loop. See design/02
-        // §"No Polling".
-        pendingImmediate = setImmediate(() => {
-          pendingImmediate = null;
-          flushBuffer();
-        });
+      } else {
+        coalescer.schedule();
       }
       callback();
     },
     flush(callback) {
-      // Cancel any pending deferred flush and flush synchronously.
-      if (pendingImmediate) {
-        clearImmediate(pendingImmediate);
-        pendingImmediate = null;
-      }
-      flushBuffer();
+      coalescer.flushSync();
       callback();
     },
   });

package/src/server/param-coercion.ts

@@ -12,23 +12,45 @@
  * 404 page. See design/07-routing.md §"Where Coercion Runs".
  */
 
+import type { Codec } from '../codec.js';
+import { toBracketKey } from '../params/resolve-schema.js';
 import type { RouteMatch } from './pipeline.js';
 import { sanitizeParamValue } from './pipeline-helpers.js';
 import { loadModule } from './safe-load.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { isDebug } from './debug.js';
 
+// ---------------------------------------------------------------------------
+// Module-level global codec store (TIM-931)
+// ---------------------------------------------------------------------------
+
+/** Global schema codecs, set once at startup from virtual:timber-schema. */
+let _globalCodecs: Record<string, Codec<unknown>> | null = null;
+
+/**
+ * Register the global schema codecs. Called once from the RSC entry
+ * at server startup when app/schema.ts provides segment param codecs.
+ * @internal
+ */
+export function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | null): void {
+  _globalCodecs = codecs;
+}
+
 /**
  * Run segment param coercion on the matched route's segments.
  *
- * Loads params.ts modules from segments that have them, extracts the
- * segmentParams definition, and coerces raw string params through codecs.
+ * When `globalCodecs` is provided (from app/schema.ts), uses the global
+ * codec map keyed by bare param name. Otherwise falls back to loading
+ * per-segment params.ts modules.
+ *
  * Throws ParamCoercionError if any codec fails (→ 404).
  *
  * This runs BEFORE middleware, so ctx.segmentParams is already typed.
  * See design/07-routing.md §"Where Coercion Runs"
+ * See design/41-global-params.md §"Pipeline Integration"
  */
 export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
+  const globalCodecs = _globalCodecs;
   // Unconditionally install a null-prototype target so the invariant
   // "match.segmentParams is null-prototype" holds from the first line,
   // regardless of whether any segment has a codec.
@@ -40,6 +62,37 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
   }
   match.segmentParams = mergeTarget as RouteMatch['segmentParams'];
 
+  // TIM-931/TIM-936: When a global schema is available, use it for coercion
+  // instead of per-segment params.ts files. The global codec map is keyed
+  // by bracket name (e.g. '[id]', '[...slug]') to avoid collisions between
+  // distinct segment types that share a param name.
+  if (globalCodecs) {
+    for (const segment of match.segments) {
+      if (!segment.paramName) continue;
+      const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
+      const codec = globalCodecs[bracketKey];
+      if (!codec) continue; // no codec in schema → keep raw string
+
+      const key = segment.paramName;
+      try {
+        mergeTarget[key] = sanitizeParamValue(codec.parse(mergeTarget[key] as string | string[]));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isDebug()) {
+          console.warn(
+            `[timber] Global schema codec rejected value for param "${key}"\n` +
+              `  Error: ${message}\n` +
+              `  Raw value: ${JSON.stringify(mergeTarget[key])}\n` +
+              `  Hint: check the codec in app/schema.ts for key '${bracketKey}'.`
+          );
+        }
+        throw new ParamCoercionError(message);
+      }
+    }
+    return;
+  }
+
+  // Legacy path: per-segment params.ts coercion
   for (const segment of match.segments) {
     // Only process segments that have a params.ts convention file
     if (!segment.params) continue;

package/src/server/pipeline-phases.ts

@@ -20,6 +20,7 @@ import {
   applyRequestHeaderOverlay,
   setMutableCookieContext,
   setSegmentParams,
+  setMatchedRoutePattern,
 } from './request-context.js';
 import { withSpan } from './tracing.js';
 import { logRenderError } from './logger.js';
@@ -418,6 +419,13 @@ export async function handleRequest(
   // See design/07-routing.md §"params.ts — Convention File for Typed Params"
   setSegmentParams(match.segmentParams);
 
+  // Store the matched route pattern for dev-mode validation in getSegmentParams().
+  // The leaf segment's urlPath is the accumulated route pattern.
+  const leaf = match.segments[match.segments.length - 1];
+  if (leaf) {
+    setMatchedRoutePattern(leaf.urlPath);
+  }
+
   // Bypass middleware for synthetic re-render requests built by the
   // action-dispatch wrapper after a no-JS form validation failure.
   // The wrapper has already executed middleware once on the inbound POST;