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

package/src/dev-tools/browser-logs.ts

@@ -264,8 +264,11 @@ export function timberDevBrowserLogs(ctx: PluginContext): Plugin {
           } else {
             process.stdout.write(formatted + '\n');
           }
-        } catch {
-          // Never let log forwarding crash the server
+        } catch (e) {
+          // Use process.stderr directly to avoid re-entering patched console
+          process.stderr.write(
+            `[timber] log forwarding failed: ${e instanceof Error ? e.message : e}\n`
+          );
         }
       });
     },

package/src/dev-tools/error-page.ts

@@ -14,11 +14,7 @@
  * Design doc: 21-dev-server.md §"Error Overlay"
  */
 
-import {
-  extractComponentStack,
-  parseFirstAppFrame,
-  type ErrorPhase,
-} from './overlay.js';
+import { extractComponentStack, parseFirstAppFrame, type ErrorPhase } from './overlay.js';
 import { classifyStack } from './stack-classifier.js';
 import { escapeHtml } from '../server/utils/escape-html.js';
 
@@ -72,7 +68,8 @@ function readSourceContext(
         highlight: start + 1 + i === line,
       })),
     };
-  } catch {
+  } catch (e) {
+    console.debug('[timber] source context extraction failed:', e instanceof Error ? e.message : e);
     return null;
   }
 }

package/src/dev-tools/logs.ts

@@ -238,8 +238,12 @@ function patchConsole(server: ViteDevServer, projectRoot: string): () => void {
         };
 
         server.hot.send('timber:server-log', payload);
-      } catch {
-        // Never let log forwarding break the server
+      } catch (e) {
+        // Use the original console.debug to avoid re-entering the patched handler
+        originals.get('debug')!(
+          '[timber] server log forwarding failed:',
+          e instanceof Error ? e.message : e
+        );
       }
     };
   }

package/src/dev-tools/overlay.ts

@@ -73,7 +73,12 @@ export const PHASE_LABELS: Record<ErrorPhase, string> = {
 
 // ─── Frame Classification (re-exported from stack-classifier) ───────────────
 
-export { classifyFrame, classifyStack, type FrameType, type ClassifiedFrame } from './stack-classifier.js';
+export {
+  classifyFrame,
+  classifyStack,
+  type FrameType,
+  type ClassifiedFrame,
+} from './stack-classifier.js';
 
 // ─── Component Stack Extraction ─────────────────────────────────────────────
 
@@ -252,7 +257,11 @@ export function calculateModuleRunnerOffset(): number {
     const beforeBody = src.slice(0, bodyIndex);
     const newlineCount = (beforeBody.match(/\n/g) || []).length;
     _cachedOffset = newlineCount;
-  } catch {
+  } catch (e) {
+    console.debug(
+      '[timber] overlay offset calculation failed:',
+      e instanceof Error ? e.message : e
+    );
     _cachedOffset = 2; // fallback to known-good value
   }
 
@@ -351,7 +360,11 @@ function rewriteStacktrace(
             const { TraceMap: TM, originalPositionFor: opf } = getTraceMapping();
             const traced = new TM(rawSourceMap);
             pos = opf(traced, { line: origLine, column: origCol });
-          } catch {
+          } catch (e) {
+            console.debug(
+              '[timber] source map tracing failed:',
+              e instanceof Error ? e.message : e
+            );
             return input;
           }
 
@@ -450,7 +463,7 @@ export function sendErrorToOverlay(
         loc: loc ? { file: loc.file, line: loc.line, column: loc.column } : undefined,
       },
     });
-  } catch {
-    // Overlay send must never crash the dev server
+  } catch (e) {
+    console.debug('[timber] overlay error send failed:', e instanceof Error ? e.message : e);
   }
 }

package/src/index.ts

@@ -51,6 +51,11 @@ import {
 
 export type { TimberUserConfig } from './config-types.js';
 
+// Global segment param schema types — re-exported from root for convenience.
+// The value export `defineSchema` lives at '@timber-js/app/params' (canonical).
+// See design/41-global-params.md.
+export type { InferCodecType, SchemaConfig } from './params/define-schema.js';
+
 // Metadata route handler types — re-exported so user-authored metadata
 // route files (sitemap.ts, robots.ts, manifest.ts, icon.tsx, etc.) can
 // import them from the package root without reaching into ./server.

package/src/params/codec-registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Client-side registry for schema segment param codecs.
+ *
+ * The Link component uses codec `serialize` functions to convert typed
+ * segment param values back to URL-safe strings. Without this registry,
+ * Link falls back to `String(value)` — which works for simple types
+ * but breaks for custom codecs (e.g., Date → '2026-04-10').
+ *
+ * Populated at startup by the browser entry importing `virtual:timber-schema`.
+ * Also usable on the server (isomorphic).
+ *
+ * Design doc: design/41-global-params.md §"Link Component"
+ */
+
+import type { Codec } from '../codec.js';
+
+let _codecs: Record<string, Codec<unknown>> | null = null;
+
+/**
+ * Register the resolved schema codecs for use by Link's URL interpolation.
+ * Called once at startup from the browser entry or RSC entry.
+ * @internal
+ */
+export function setLinkCodecs(codecs: Record<string, Codec<unknown>> | null): void {
+  _codecs = codecs;
+}
+
+/**
+ * Look up a codec by bracket key (e.g. '[id]', '[...slug]').
+ * Returns undefined if no schema is registered or the key has no codec.
+ */
+export function getLinkCodec(bracketKey: string): Codec<unknown> | undefined {
+  return _codecs?.[bracketKey] ?? undefined;
+}

package/src/params/define-schema.ts

@@ -0,0 +1,72 @@
+/**
+ * defineSchema — global segment param schema definition.
+ *
+ * Identity function at runtime; the type information is what matters.
+ * The Vite plugin reads the schema at build time for codegen, and
+ * the pipeline reads it at runtime for coercion.
+ *
+ * Design doc: design/41-global-params.md
+ */
+
+import type { Codec } from '../codec.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.
+ *
+ * Used by codegen to reference schema types without hardcoding:
+ *   `InferCodecType<typeof schema.segmentParams['[year]']>`
+ */
+export type InferCodecType<V> =
+  V extends Codec<infer T>
+    ? T
+    : V extends StandardSchemaV1<infer T>
+      ? T
+      : V extends { parseServerSide: (value: string) => infer T }
+        ? T
+        : string;
+
+/** Acceptable codec value for segment params: a Codec or Standard Schema. */
+type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+
+/** Configuration object for defineSchema. */
+export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
+  segmentParams: S;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Define the global segment param schema.
+ *
+ * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,
+ * `[[...slug]]`) mapped to a codec. This makes the relationship between
+ * filesystem segments and codecs visually obvious.
+ *
+ * A dynamic segment with no key here defaults to `string` at codegen time.
+ *
+ * ```ts
+ * // app/schema.ts
+ * import { defineSchema, codec } from '@timber-js/app';
+ * import { z } from 'zod';
+ *
+ * export default defineSchema({
+ *   segmentParams: {
+ *     '[artistSlug]': codec.string,
+ *     '[year]': codec.integer,
+ *     '[id]': z.coerce.number().int(),
+ *   },
+ * });
+ * ```
+ */
+export function defineSchema<S extends Record<string, SegmentParamCodec>>(
+  config: SchemaConfig<S>
+): SchemaConfig<S> {
+  return config;
+}

package/src/params/index.ts

@@ -0,0 +1,11 @@
+// @timber-js/app/params — Global segment param schema and typed accessors.
+//
+// This is the import path for defineSchema, InferCodecType, and
+// the future getSegmentParams/useSegmentParams with route narrowing.
+//
+// See design/41-global-params.md
+
+export { defineSchema } from './define-schema.js';
+export type { InferCodecType, SchemaConfig } from './define-schema.js';
+export { resolveSchemaCodecs, toBracketKey } from './resolve-schema.js';
+export { setLinkCodecs, getLinkCodec } from './codec-registry.js';

package/src/params/resolve-schema.ts

@@ -0,0 +1,88 @@
+/**
+ * Schema resolution — resolves the global schema's segmentParams into
+ * a runtime-ready codec map keyed by bracket name (e.g. '[id]').
+ *
+ * Bracket keys are preserved so that `[id]`, `[...id]`, and `[[...id]]`
+ * remain distinct entries. The coercion layer reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Design doc: design/41-global-params.md §Pipeline Integration
+ */
+
+import type { Codec } from '../codec.js';
+import { isCodec, isStandardSchema, validateSync } from '../schema-bridge.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+/**
+ * Wrap a Standard Schema into a Codec for route params.
+ * Parse throws on failure (invalid param → 404). Serialize returns string.
+ */
+function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      const result = validateSync(schema, value);
+      if (!result.issues) {
+        return result.value;
+      }
+      const messages = result.issues.map((i) => i.message).join(', ');
+      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+    },
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) return null;
+      if (Array.isArray(value)) return value.join('/');
+      return String(value);
+    },
+  };
+}
+
+/**
+ * Resolve a schema entry to a Codec. Accepts Codec<T> or StandardSchemaV1<T>.
+ */
+function resolveCodec(fieldName: string, value: unknown): Codec<unknown> {
+  if (isCodec(value)) return value;
+  if (isStandardSchema(value)) return fromParamSchema(fieldName, value);
+  throw new Error(`[timber] Schema field '${fieldName}' is not a valid codec or Standard Schema.`);
+}
+
+/**
+ * Reconstruct the bracket key for a segment from its type and param name.
+ * Used by the coercion layer to look up codecs in the bracket-keyed map.
+ *
+ * 'dynamic'          + 'id'   → '[id]'
+ * 'catch-all'        + 'slug' → '[...slug]'
+ * 'optional-catch-all' + 'slug' → '[[...slug]]'
+ */
+export function toBracketKey(segmentType: string, paramName: string): string {
+  switch (segmentType) {
+    case 'catch-all':
+      return `[...${paramName}]`;
+    case 'optional-catch-all':
+      return `[[...${paramName}]]`;
+    default:
+      return `[${paramName}]`;
+  }
+}
+
+/**
+ * Resolve the global schema's segmentParams into a map of bracket-keyed
+ * param name → resolved Codec.
+ *
+ * Keys are preserved exactly as written in `app/schema.ts` so that
+ * `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.
+ * The coercion layer in `param-coercion.ts` reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }
+ * Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }
+ */
+export function resolveSchemaCodecs(
+  segmentParams: Record<string, unknown>
+): Record<string, Codec<unknown>> {
+  const resolved: Record<string, Codec<unknown>> = Object.create(null);
+
+  for (const [bracketName, value] of Object.entries(segmentParams)) {
+    resolved[bracketName] = resolveCodec(bracketName, value);
+  }
+
+  return resolved;
+}

package/src/plugins/dev-server.ts

@@ -190,20 +190,25 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       handler = rscModule.default as (req: Request) => Promise<Response>;
 
       // Wire pipeline errors into the browser error overlay.
-      // setDevPipelineErrorHandler is only defined in dev (rsc-entry.ts exports it).
-      // The handler receives optional RSC debug component data (component names,
-      // environments, stack frames) from the Flight debug channel for render errors.
-      const setHandler = rscModule.setDevPipelineErrorHandler as
-        | ((
-            fn: (
+      // Set devPipelineErrorHandler directly on the pipeline config —
+      // no module-level singleton. The handler receives optional RSC debug
+      // component data (component names, environments, stack frames) from
+      // the Flight debug channel for render errors.
+      const config = rscModule.pipelineConfig as
+        | {
+            devPipelineErrorHandler?: (
               error: Error,
               phase: string,
-              debugComponents?: Array<{ name: string; env: string | null; stack: unknown[] | null }>
-            ) => void
-          ) => void)
+              debugComponents?: Array<{
+                name: string;
+                env: string | null;
+                stack: unknown[] | null;
+              }>
+            ) => void;
+          }
         | undefined;
-      if (typeof setHandler === 'function') {
-        setHandler((error, _phase, debugComponents) => {
+      if (config) {
+        config.devPipelineErrorHandler = (error, _phase, debugComponents) => {
           sendErrorToOverlay(
             server,
             error,
@@ -211,7 +216,7 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
             projectRoot,
             debugComponents
           );
-        });
+        };
       }
 
       // Wire source-map handler so error pages show original positions.
@@ -316,8 +321,11 @@ function respond500(
       res.setHeader('content-type', 'text/html; charset=utf-8');
       res.end(html);
       return;
-    } catch {
-      // Fall through to text/plain if the HTML generator fails
+    } catch (e) {
+      console.debug(
+        '[timber] dev error page generation failed, falling back to text/plain:',
+        e instanceof Error ? e.message : e
+      );
     }
   }
 
@@ -524,8 +532,8 @@ function listenForClientErrors(server: ViteDevServer, projectRoot: string): void
           loc: loc ? { file: loc.file, line: loc.line, column: loc.column } : undefined,
         },
       });
-    } catch {
-      // Overlay send must never crash the dev server
+    } catch (e) {
+      console.debug('[timber] overlay send failed:', e instanceof Error ? e.message : e);
     }
   });
 }

package/src/plugins/mdx.ts

@@ -92,7 +92,11 @@ async function tryImport(name: string, projectRoot: string): Promise<unknown | u
     try {
       const mod = await import(name);
       return mod.default ?? mod;
-    } catch {
+    } catch (e) {
+      console.debug(
+        `[timber] optional MDX dependency '${name}' not available:`,
+        e instanceof Error ? e.message : e
+      );
       return undefined;
     }
   }

package/src/plugins/routing.ts

@@ -15,6 +15,11 @@ import { join } from 'node:path';
 import { scanRoutes } from '../routing/scanner.js';
 import { generateRouteMap } from '../routing/codegen.js';
 import { collectInterceptionRewrites } from '../routing/interception.js';
+import {
+  collectDynamicSegments,
+  findSchemaFile,
+  parseExistingSchemaKeys,
+} from '../cli-schema-sync.js';
 
 import {
   lintConventions,
@@ -42,11 +47,19 @@ const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
 const SEARCH_PARAMS_REGISTRY_ID = 'virtual:timber-search-params-registry';
 const RESOLVED_SEARCH_PARAMS_REGISTRY_ID = `\0${SEARCH_PARAMS_REGISTRY_ID}`;
 
+// TIM-931: Schema virtual module.
+//
+// When app/schema.ts exists, this module imports it and resolves the
+// bracket-keyed segmentParams codecs into a bare-name codec map for
+// runtime coercion. When no schema exists, exports null.
+const SCHEMA_ID = 'virtual:timber-schema';
+const RESOLVED_SCHEMA_ID = `\0${SCHEMA_ID}`;
+
 /**
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|schema|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
@@ -126,6 +139,11 @@ export function timberRouting(ctx: PluginContext): Plugin {
     ctx.timer.end('route-scan');
     writeCodegen(ctx);
 
+    // Dev: warn about dynamic segments not registered in app/schema.ts.
+    // Only logs a suggestion, never auto-modifies the schema file.
+    // See design/41-global-params.md §Auto-Scaffolding
+    warnUnregisteredSegments(ctx);
+
     // Lint conventions (empty app, missing methods, missing root layout)
     const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
     const newConventionWarnings = conventionWarnings.filter((w) => !warnedFiles.has(w.id));
@@ -168,6 +186,11 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_SEARCH_PARAMS_REGISTRY_ID;
       }
 
+      // TIM-931: Schema virtual module
+      if (cleanId === SCHEMA_ID || cleanId.endsWith(`/${SCHEMA_ID}`)) {
+        return RESOLVED_SCHEMA_ID;
+      }
+
       return null;
     },
 
@@ -193,6 +216,10 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return generateSearchParamsRegistryModule(ctx.routeTree!);
       }
 
+      if (id === RESOLVED_SCHEMA_ID) {
+        return generateSchemaModule(ctx.appDir);
+      }
+
       return null;
     },
 
@@ -275,12 +302,46 @@ export function timberRouting(ctx: PluginContext): Plugin {
  * When the route tree changes, any environment that has imported the manifest
  * needs to be invalidated so the next request/transform picks up the new tree.
  */
+/** Set of segments we've already warned about — avoid repeating on every rescan. */
+const _warnedSegments = new Set<string>();
+
+/**
+ * Warn about dynamic segments not registered in app/schema.ts.
+ * Only fires when a schema file exists. Logs once per segment per session.
+ */
+function warnUnregisteredSegments(ctx: PluginContext): void {
+  const schemaPath = findSchemaFile(ctx.appDir);
+  if (!schemaPath) return;
+
+  const filesystemSegments = collectDynamicSegments(ctx.appDir);
+  if (filesystemSegments.length === 0) return;
+
+  const content = readFileSync(schemaPath, 'utf-8');
+  const existingKeys = parseExistingSchemaKeys(content);
+  const missing = filesystemSegments.filter(
+    (seg) => !existingKeys.includes(seg) && !_warnedSegments.has(seg)
+  );
+
+  if (missing.length === 0) return;
+
+  for (const seg of missing) _warnedSegments.add(seg);
+
+  console.warn(
+    `[timber] New segment${missing.length > 1 ? 's' : ''} not in schema: ${missing.join(', ')}\n` +
+      `  Run: timber schema sync`
+  );
+}
+
 function invalidateManifest(server: ViteDevServer): void {
   for (const envName of Object.keys(server.environments)) {
     const env = server.environments[envName];
     if (!env?.moduleGraph) continue;
 
-    for (const virtualId of [RESOLVED_VIRTUAL_ID, RESOLVED_SEARCH_PARAMS_REGISTRY_ID]) {
+    for (const virtualId of [
+      RESOLVED_VIRTUAL_ID,
+      RESOLVED_SEARCH_PARAMS_REGISTRY_ID,
+      RESOLVED_SCHEMA_ID,
+    ]) {
       const mod = env.moduleGraph.getModuleById(virtualId);
       if (mod) {
         env.moduleGraph.invalidateModule(mod);
@@ -301,6 +362,50 @@ function invalidateManifest(server: ViteDevServer): void {
  * <Link> can look up the definition from the original `href` prop before
  * segmentParams are interpolated.
  */
+/** Schema file extensions to check, in priority order. */
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * TIM-931: Generate the virtual:timber-schema module.
+ *
+ * When app/schema.{ts,tsx,js,jsx} exists, generates a module that
+ * imports the schema and resolves its segmentParams codecs into a
+ * bare-name codec map for runtime coercion.
+ *
+ * When no schema exists, exports null.
+ */
+function generateSchemaModule(appDir: string): string {
+  let schemaPath: string | null = null;
+  for (const ext of SCHEMA_EXTENSIONS) {
+    const candidate = join(appDir, `schema${ext}`);
+    if (existsSync(candidate)) {
+      schemaPath = candidate;
+      break;
+    }
+  }
+
+  if (!schemaPath) {
+    return [
+      '// Auto-generated schema loader — no app/schema.ts found.',
+      'export default null;',
+    ].join('\n');
+  }
+
+  return [
+    '// Auto-generated schema loader — do not edit.',
+    '// Generated by timber-routing plugin (TIM-931).',
+    '',
+    `import schema from ${JSON.stringify(schemaPath)};`,
+    `import { resolveSchemaCodecs } from '@timber-js/app/params';`,
+    '',
+    'const globalCodecs = schema?.segmentParams',
+    '  ? resolveSchemaCodecs(schema.segmentParams)',
+    '  : null;',
+    '',
+    'export default globalCodecs;',
+  ].join('\n');
+}
+
 function generateSearchParamsRegistryModule(tree: RouteTree): string {
   const entries: Array<{ urlPath: string; filePath: string }> = [];
 

package/src/routing/codegen-shared.ts

@@ -80,6 +80,17 @@ export function buildCodecChainType(
   return inner;
 }
 
+/**
+ * Build a TypeScript type expression for a single param using the global
+ * schema's InferCodecType. Falls back to `fallback` when schema doesn't
+ * declare this param.
+ *
+ * Generates: `InferCodecType<typeof schema.segmentParams['[paramName]']>`
+ */
+export function buildSchemaParamType(p: ParamEntry): string {
+  return `InferCodecType<typeof schema.segmentParams[${JSON.stringify(p.bracketName)}]>`;
+}
+
 /**
  * Format the searchParams type for a route entry.
  *

package/src/routing/codegen-types.ts

@@ -18,10 +18,15 @@ export interface RouteEntry {
   searchParamsPagePath?: string;
   /** Whether this is an API route (route.ts) vs page route */
   isApiRoute: boolean;
+  /** Whether a global schema (app/schema.ts) exists for this app */
+  hasSchema?: boolean;
 }
 
 export interface ParamEntry {
   name: string;
+  /** Bracket-wrapped segment name as it appears in the filesystem and schema.
+   *  e.g. '[id]', '[...slug]', '[[...slug]]' */
+  bracketName: string;
   type: 'string' | 'string[]' | 'string[] | undefined';
   /**
    * Ordered list of params.ts files in the route chain that may declare