@timber-js/app 0.2.0-alpha.164 → 0.2.0-alpha.166

package/dist/server/stream-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../../src/server/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,CAAC,EAAE,UAAU,GACnB,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAmK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,UAAU,CAAC,CA0D5B"}
+{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../../src/server/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,CAAC,EAAE,UAAU,GACnB,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAmK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,UAAU,CAAC,CA4D5B"}

package/docs/api/33-api-search-params.mdx

@@ -23,6 +23,19 @@ export const searchParams = defineSearchParams({
 });
 ```
 
+### Implicit optionality
+
+Search params are optional by nature — the URL might not contain them. A schema without `.default()` or `.optional()` (e.g. bare `z.string()`) is treated as implicitly optional: absent or invalid input parses to `undefined`, and the field's inferred type widens to `T | undefined`. Definitions never throw at module-eval time, and schema-backed parsing never throws at request time.
+
+```ts
+const def = defineSearchParams({ name: z.string() });
+def.parse(new URLSearchParams(''));        // { name: undefined }
+def.parse(new URLSearchParams('name=x'));  // { name: 'x' }
+// Inferred type: { name: string | undefined }
+```
+
+Note: `z.coerce.*` schemas declare input `unknown`, so a coerce schema without `.default()` keeps its narrow type even though absent input yields `undefined` at runtime — add `.default()` to coerce schemas for accurate types.
+
 ### Returns: `SearchParamsDefinition<T>`
 
 | Method / Property         | Description                                            |

package/docs/learn/00-introduction.mdx

@@ -61,8 +61,7 @@ export const searchParams = defineSearchParams({
 const sp = searchParams.get();
 
 // or on the client
-
-const [sp, setSearchParams] = searchParams.useQueryState();
+const [sp, setSearchParams] = searchParams.useQueryStates();
 ```
 
 ### Typed Routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.164",
+  "version": "0.2.0-alpha.166",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -150,6 +150,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "copy-docs": "node scripts/copy-docs.js",
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
+    "typecheck": "tsgo --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.8.0",
@@ -195,10 +201,5 @@
   },
   "engines": {
     "node": ">=22.18.0"
-  },
-  "scripts": {
-    "copy-docs": "node scripts/copy-docs.js",
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
-    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/adapters/nitro.ts

@@ -5,9 +5,9 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile } from 'node:fs/promises';
+import { writeFile, readFile, cp, glob } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
+import { join, relative, dirname, basename } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
 import { IMMUTABLE_CACHE } from './shared.js';
@@ -38,6 +38,12 @@ interface PresetConfig {
   nitroPreset: string;
   /** Output directory name within the build dir. */
   outputDir: string;
+  /**
+   * Path to the server bundle directory relative to outputDir.
+   * Nitro places the bundled server entry + _chunks/ here.
+   * Most presets use `server`; Vercel uses `functions/__server.func`.
+   */
+  serverBundleDir: string;
   /** Whether the runtime supports waitUntil. */
   supportsWaitUntil: boolean;
   /** Whether the runtime supports application-level 103 Early Hints. */
@@ -52,6 +58,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel': {
     nitroPreset: 'vercel',
     outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel',
@@ -60,6 +67,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel-edge': {
     nitroPreset: 'vercel-edge',
     outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel-edge',
@@ -67,6 +75,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify': {
     nitroPreset: 'netlify',
     outputDir: '.netlify/functions-internal',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'netlify',
@@ -74,6 +83,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify-edge': {
     nitroPreset: 'netlify-edge',
     outputDir: '.netlify/edge-functions',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'netlify-edge',
@@ -81,6 +91,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'aws-lambda': {
     nitroPreset: 'aws-lambda',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'aws-lambda',
@@ -88,6 +99,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'deno-deploy': {
     nitroPreset: 'deno-deploy',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'deno-deploy',
@@ -95,6 +107,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'azure-functions': {
     nitroPreset: 'azure-functions',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'azure-functions',
@@ -102,6 +115,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'node-server': {
     nitroPreset: 'node-server',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     // Disabled by default: most node-server deployments sit behind a
     // reverse proxy (nginx, caddy, traefik) that doesn't support 103
@@ -116,6 +130,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'bun': {
     nitroPreset: 'bun',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     // Disabled for same reason as node-server — reverse proxies choke on 103.
     // Link headers on the 200 response are converted to 103 by CDNs.
@@ -220,7 +235,29 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       // Run the Nitro build to produce a production-ready server bundle.
       // The output goes to dist/nitro/.output/server/index.mjs (for node-server preset).
       // Config is passed programmatically — no nitro.config.ts file needed.
-      await runNitroBuild(outDir, preset, options.nitroConfig);
+      const { serverDir } = await runNitroBuild(outDir, preset, options.nitroConfig);
+
+      // Copy prebuilt flight payloads from the canonical build source
+      // (buildDir/prebuilt, cleaned by the prebuilt plugin each build) into
+      // the Nitro output. The RSC entry resolves `../prebuilt/` relative to
+      // its bundled chunk (<serverDir>/_chunks/), so prebuilt/ must live at
+      // <serverDir>/prebuilt/. serverDir is the resolved path from Nitro
+      // (honors user overrides via nitroConfig.output.serverDir).
+      const prebuiltSrc = join(buildDir, 'prebuilt');
+      await cp(prebuiltSrc, join(serverDir, 'prebuilt'), {
+        recursive: true,
+      }).catch((e: NodeJS.ErrnoException) => {
+        if (e.code !== 'ENOENT') throw e;
+      });
+
+      // Vercel with functionRules clones __server.func to per-route .func
+      // directories during the Nitro build. Copy prebuilt into those clones
+      // so requests routed to them also resolve ../prebuilt correctly.
+      if (preset === 'vercel' || preset === 'vercel-edge') {
+        const functionsDir = dirname(serverDir);
+        const baseFuncName = basename(serverDir);
+        await copyPrebuiltToVercelFuncClones(functionsDir, prebuiltSrc, baseFuncName);
+      }
     },
 
     // Only presets that produce a locally-runnable server get preview().
@@ -598,11 +635,16 @@ export function generateNitroPreviewCommand(
  * Externalizes the timber RSC/SSR output — those files are pre-built
  * by timber and have internal references that nitro's bundler can't follow.
  */
+interface NitroBuildResult {
+  /** Resolved output.serverDir — where the server bundle + _chunks/ live. */
+  serverDir: string;
+}
+
 async function runNitroBuild(
   nitroDir: string,
   preset: NitroPreset,
   userConfig?: Record<string, unknown>
-): Promise<void> {
+): Promise<NitroBuildResult> {
   const presetConfig = PRESET_CONFIGS[preset];
   const {
     createNitro,
@@ -633,10 +675,18 @@ async function runNitroBuild(
     ...userConfig,
   });
 
+  // Read the resolved serverDir AFTER config merging — userConfig may
+  // override output.dir or output.serverDir. Nitro appends a trailing
+  // slash during resolution; strip it for join() compatibility.
+  const raw = nitro.options.output.serverDir;
+  const serverDir = raw.endsWith('/') ? raw.slice(0, -1) : raw;
+
   await prepare(nitro);
   await copyPublicAssets(nitro);
   await nitroBuild(nitro);
   await nitro.close();
+
+  return { serverDir };
 }
 
 /** Spawn a Nitro preview process and pipe stdio. */
@@ -729,3 +779,55 @@ export function sendNodeResponse(nodeRes, webRes) {
 export function getPresetConfig(preset: NitroPreset): PresetConfig {
   return PRESET_CONFIGS[preset];
 }
+
+/**
+ * Resolve the destination path for prebuilt flight payloads in the Nitro
+ * output directory. The RSC entry resolves `../prebuilt/` relative to its
+ * bundled chunk location (`<serverBundleDir>/_chunks/`), so prebuilt/ must
+ * live at `<serverBundleDir>/prebuilt/`.
+ *
+ * The serverBundleDir varies by preset — Nitro's Vercel preset uses
+ * `functions/__server.func` while most others use `server`.
+ *
+ * @internal Exported for testing.
+ */
+export function resolvePrebuiltOutputPath(outDir: string, preset: NitroPreset): string {
+  const presetConfig = PRESET_CONFIGS[preset];
+  return join(outDir, presetConfig.outputDir, presetConfig.serverBundleDir, 'prebuilt');
+}
+
+/**
+ * Copy prebuilt payloads into cloned Vercel function directories.
+ *
+ * When users configure `vercel.functionRules`, Nitro's compiled hook clones
+ * the base __server.func to per-route .func directories. These clones are
+ * created during `runNitroBuild()` — before our post-build prebuilt copy.
+ * Each clone resolves `../prebuilt` independently, so they each need a copy.
+ *
+ * @internal Exported for testing.
+ */
+export async function copyPrebuiltToVercelFuncClones(
+  functionsDir: string,
+  prebuiltSrc: string,
+  baseFuncName: string
+): Promise<void> {
+  const funcDirs: string[] = [];
+  try {
+    for await (const match of glob('**/*.func', { cwd: functionsDir })) {
+      if (!match.endsWith(baseFuncName)) {
+        funcDirs.push(join(functionsDir, match));
+      }
+    }
+  } catch {
+    return;
+  }
+  await Promise.all(
+    funcDirs.map((dir) =>
+      cp(prebuiltSrc, join(dir, 'prebuilt'), { recursive: true }).catch(
+        (e: NodeJS.ErrnoException) => {
+          if (e.code !== 'ENOENT') throw e;
+        }
+      )
+    )
+  );
+}

package/src/client/use-query-states.ts

@@ -22,19 +22,71 @@ import { getSearchParamsDefinition } from '../search-params/registry.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────
 
+// nuqs's parser contract conflates values timber codecs distinguish:
+// parse() returning null means "unparseable, substitute defaultValue",
+// and undefined entries are skipped entirely. Timber codecs can
+// legitimately produce both — bare z.string() yields undefined for absent
+// params (implicit optionality), and a codec may map a present value to
+// null. Wrap those two values in sentinels across the nuqs boundary and
+// unwrap them before handing values back to the caller, so the client
+// hook returns exactly what server-side parse() returns.
+// Unique object references compared by identity — a codec can never
+// produce these from URL input, so user-controlled strings cannot collide
+// with them (unlike string sentinels), and unlike Symbols they survive
+// nuqs's internal string coercion without throwing.
+const NULL_SENTINEL: object = { timberSentinel: 'null' };
+const UNDEFINED_SENTINEL: object = { timberSentinel: 'undefined' };
+
+function wrapNuqsValue(value: unknown): unknown {
+  if (value === null) return NULL_SENTINEL;
+  if (value === undefined) return UNDEFINED_SENTINEL;
+  return value;
+}
+
+function unwrapNuqsValue(value: unknown): unknown {
+  if (value === NULL_SENTINEL) return null;
+  if (value === UNDEFINED_SENTINEL) return undefined;
+  return value;
+}
+
 /**
  * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
  *
  * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
  * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
+ *
+ * The defaultValue is computed eagerly. Codecs are documented to return a
+ * default rather than throw, but a throwing codec must not crash every
+ * component that mounts the hook — treat its default as undefined and let
+ * its error surface from server-side parse() instead.
  */
 function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {
+  let defaultValue: unknown;
+  try {
+    defaultValue = codec.parse(undefined);
+  } catch {
+    defaultValue = undefined;
+  }
   return {
-    parse: (v: string) => codec.parse(v),
-    serialize: (v: T) => codec.serialize(v) ?? '',
-    defaultValue: codec.parse(undefined) as T,
-    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),
-  };
+    parse: (v: string) => wrapNuqsValue(codec.parse(v)),
+    serialize: (v: unknown) => {
+      const value = unwrapNuqsValue(v);
+      // Delegate null to the codec — some codecs encode null as a real
+      // query value. undefined has no encoding; nuqs requires a string.
+      return value === undefined ? '' : (codec.serialize(value as T) ?? '');
+    },
+    defaultValue: wrapNuqsValue(defaultValue),
+    eq: (a: unknown, b: unknown) => {
+      if (a === b) return true;
+      try {
+        return (
+          codec.serialize(unwrapNuqsValue(a) as T) === codec.serialize(unwrapNuqsValue(b) as T)
+        );
+      } catch {
+        return false;
+      }
+    },
+  } as SingleParser<T> & { defaultValue: T };
 }
 
 /**
@@ -124,6 +176,19 @@ export function useQueryStates<T extends Record<string, unknown>>(
     throw err;
   }
 
+  // Unwrap the null/undefined sentinels the bridge injected (see Codec
+  // Bridge above) so callers see exactly what server-side parse() returns.
+  // Copy-on-write preserves the identity of nuqs's memoized values object
+  // when nothing needs unwrapping.
+  let normalized = values;
+  for (const key of Object.keys(bridged)) {
+    const value = normalized[key];
+    if (value === NULL_SENTINEL || value === UNDEFINED_SENTINEL) {
+      if (normalized === values) normalized = { ...values };
+      normalized[key] = unwrapNuqsValue(value);
+    }
+  }
+
   // Wrap the nuqs setter to match timber's SetParams<T> signature.
   // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.
   // timber's setter accepts Partial<T> with optional SetParamsOptions.
@@ -132,11 +197,38 @@ export function useQueryStates<T extends Record<string, unknown>>(
     if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;
     if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;
     if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;
+    // nuqs's update loop skips undefined entries and treats null as a
+    // key deletion before serialize runs. Timber semantics:
+    //   - setParams({ q: undefined }) must clear ?q= (absent = undefined),
+    //     so explicit undefined maps to a null deletion.
+    //   - setParams({ q: null }) clears the key only when the codec encodes
+    //     null as "omit" (serialize(null) === null). If the codec encodes
+    //     null as a real query value, forward the sentinel so the bridged
+    //     serialize writes it — matching definition.serialize({ q: null }).
+    let forwarded: Record<string, unknown> = partial;
+    for (const key of Object.keys(partial)) {
+      const value = partial[key as keyof T];
+      if (value === undefined) {
+        if (forwarded === partial) forwarded = { ...partial };
+        forwarded[key] = null;
+      } else if (value === null) {
+        let encoded: string | null = null;
+        try {
+          encoded = codecs[key as keyof T]?.serialize(null as T[keyof T]) ?? null;
+        } catch {
+          // Codec can't serialize null — treat as a deletion.
+        }
+        if (encoded !== null) {
+          if (forwarded === partial) forwarded = { ...partial };
+          forwarded[key] = NULL_SENTINEL;
+        }
+      }
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    void setValues(partial as any, nuqsSetOptions);
+    void setValues(forwarded as any, nuqsSetOptions);
   };
 
-  return [values as T, setParams];
+  return [normalized as T, setParams];
 }
 
 // ─── Definition binding ───────────────────────────────────────────

package/src/dev-tools/logs.ts

@@ -12,9 +12,86 @@
  * Design docs: 18-build-system.md §"Dev Server", 02-rendering-pipeline.md
  */
 
-import type { Plugin, ViteDevServer } from 'vite';
+import type { Plugin, ViteDevServer, Logger } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 
+// ─── Original Console Snapshot ──────────────────────────────────────────
+
+/**
+ * Snapshot of the original console methods, captured at module load time
+ * (before any patching). Used as Vite's `customLogger` console so that
+ * forwardConsole output bypasses our patch entirely — eliminating the
+ * server→browser→server forwarding loop without string matching.
+ */
+export const originalConsole: Pick<Console, 'log' | 'warn' | 'error' | 'debug' | 'info'> = {
+  log: console.log.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+  info: console.info.bind(console),
+};
+
+/**
+ * Wrap a Vite Logger so its output methods route through `originalConsole`
+ * instead of the global (potentially patched) console. This prevents the
+ * server→browser→server forwarding loop even when the user supplies their
+ * own `customLogger` that internally calls console methods.
+ */
+export function wrapLoggerWithOriginalConsole(logger: Logger): Logger {
+  // Swap all patched console methods to originals during any logger call,
+  // since user loggers may call any combination of console methods internally.
+  function withOriginals<T>(fn: () => T): T {
+    const saved = {
+      log: console.log,
+      warn: console.warn,
+      error: console.error,
+      debug: console.debug,
+      info: console.info,
+    };
+    console.log = originalConsole.log;
+    console.warn = originalConsole.warn;
+    console.error = originalConsole.error;
+    console.debug = originalConsole.debug;
+    console.info = originalConsole.info;
+    try {
+      return fn();
+    } finally {
+      console.log = saved.log;
+      console.warn = saved.warn;
+      console.error = saved.error;
+      console.debug = saved.debug;
+      console.info = saved.info;
+    }
+  }
+
+  return {
+    get hasWarned() {
+      return logger.hasWarned;
+    },
+    set hasWarned(v) {
+      logger.hasWarned = v;
+    },
+    info(msg, opts) {
+      withOriginals(() => logger.info(msg, opts));
+    },
+    warn(msg, opts) {
+      withOriginals(() => logger.warn(msg, opts));
+    },
+    warnOnce(msg, opts) {
+      withOriginals(() => logger.warnOnce(msg, opts));
+    },
+    error(msg, opts) {
+      withOriginals(() => logger.error(msg, opts));
+    },
+    clearScreen(type) {
+      logger.clearScreen(type);
+    },
+    hasErrorLogged(error) {
+      return logger.hasErrorLogged(error);
+    },
+  };
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────
 
 /** Log levels that are patched and forwarded. */
@@ -215,50 +292,58 @@ export function isFrameworkInternalCaller(): boolean {
  * 3. Sends via server.hot.send() — dropped if no clients connected
  */
 function patchConsole(server: ViteDevServer, projectRoot: string): () => void {
-  const originals = new Map<ServerLogLevel, (...args: unknown[]) => void>();
+  const prevConsole = new Map<ServerLogLevel, (...args: unknown[]) => void>();
+  // Per-level guard so a console.warn inside a console.error handler isn't
+  // suppressed — only same-level synchronous re-entrancy is blocked.
+  const patchingLevel = new Set<ServerLogLevel>();
 
   for (const level of LOG_LEVELS) {
-    originals.set(level, console[level].bind(console));
+    prevConsole.set(level, console[level].bind(console));
 
     console[level] = (...args: unknown[]) => {
-      // Always call the original — server terminal output is preserved
-      originals.get(level)!(...args);
-
-      // Skip framework-internal logs (plugins/, adapters/) from browser forwarding.
-      // Server runtime logs (render errors, action errors, etc.) are preserved.
-      if (isFrameworkInternalCaller()) return;
-
-      // Break the server→browser→server console forwarding loop. Vite's
-      // forwardConsole re-logs browser console output on the server via
-      // `logger.error("[console.error] ...")`. Our patch would send it back
-      // to the browser, Vite's client patch forwards it again → exponential
-      // log spam. Detect the `[console.<level>]` prefix Vite adds and skip.
-      if (typeof args[0] === 'string' && args[0].includes('[console.')) return;
+      // Same-level re-entrancy guard: if prevConsole's wrapper calls back
+      // into console[level], just pass through without forwarding.
+      if (patchingLevel.has(level)) {
+        prevConsole.get(level)!(...args);
+        return;
+      }
 
-      // Serialize and forward to browser
+      patchingLevel.add(level);
       try {
-        const payload: ServerLogPayload = {
-          level,
-          args: args.map((arg) => serializeArg(arg)),
-          location: extractCallerLocation(projectRoot),
-          timestamp: Date.now(),
-        };
-
-        server.hot.send('timber:server-log', payload);
-      } 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
-        );
+        // Call the previous console method first — guarantees terminal output
+        // even if serialization or forwarding fails downstream. If prevConsole
+        // throws, the error propagates (not swallowed) but patchingLevel is
+        // still cleaned up by the outer finally.
+        prevConsole.get(level)!(...args);
+
+        // Skip framework-internal logs (plugins/, adapters/) from browser forwarding.
+        if (isFrameworkInternalCaller()) return;
+
+        try {
+          const payload: ServerLogPayload = {
+            level,
+            args: args.map((arg) => serializeArg(arg)),
+            location: extractCallerLocation(projectRoot),
+            timestamp: Date.now(),
+          };
+
+          server.hot.send('timber:server-log', payload);
+        } catch (e) {
+          originalConsole.debug(
+            '[timber] server log forwarding failed:',
+            e instanceof Error ? e.message : e
+          );
+        }
+      } finally {
+        patchingLevel.delete(level);
       }
     };
   }
 
-  // Return a cleanup function to restore originals
+  // Return a cleanup function to restore the previous console methods
   return () => {
-    for (const [level, original] of originals) {
-      console[level] = original;
+    for (const [level, prev] of prevConsole) {
+      console[level] = prev;
     }
   };
 }

package/src/index.ts

@@ -11,6 +11,7 @@
  */
 
 import type { Plugin, PluginOption } from 'vite';
+import { createLogger } from 'vite';
 import { join, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import react, { reactCompilerPreset } from '@vitejs/plugin-react';
@@ -23,7 +24,7 @@ import { timberShims } from './plugins/shims';
 import { timberFonts } from './plugins/fonts';
 import { timberStaticBuild } from './plugins/static-build';
 import { timberBuildManifest } from './plugins/build-manifest';
-import { timberDevLogs } from './dev-tools/logs';
+import { timberDevLogs, originalConsole, wrapLoggerWithOriginalConsole } from './dev-tools/logs';
 import { resolveForwardConsole } from './dev-tools/browser-logs';
 import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
@@ -438,10 +439,22 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // on the devBrowserLogs config (default: 'warn'). See TIM-1152.
       serverConfig.forwardConsole = resolveForwardConsole(ctx.config.devBrowserLogs);
 
+      // Provide a customLogger whose output routes through the pre-patched
+      // console methods so Vite's forwardConsole output never re-enters our
+      // server→browser patch. If the user supplied their own customLogger,
+      // wrap it so its console calls also bypass patching.
+      const customLogger = userConfig.customLogger
+        ? wrapLoggerWithOriginalConsole(userConfig.customLogger)
+        : createLogger(userConfig.logLevel ?? 'info', {
+            allowClearScreen: userConfig.clearScreen ?? true,
+            console: originalConsole as Console,
+          });
+
       return {
         build: { outDir: buildOutDir },
         environments: envOutDirs,
         optimizeDeps: { exclude: timberOptimizeDepsExclude },
+        customLogger,
         server: serverConfig,
         preview: previewConfig,
       };

package/src/schema-bridge.ts

@@ -184,9 +184,10 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
         return defaultResult.value;
       }
 
-      // No default available — return undefined (codec design choice).
-      // Callers like defineSearchParams validate this at definition time
-      // via validateSchemaDefaults() to catch it early.
+      // No default available — the field is implicitly optional. Return
+      // undefined; defineSearchParams widens the field's inferred type to
+      // T | undefined via InferField so this doesn't lie.
+      // design/23-search-params.md §"Implicit Optionality"
       return undefined as T;
     },