@timber-js/app 0.2.0-alpha.165 → 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.165",
+  "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/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;
     },
 

package/src/search-params/define.ts

@@ -11,7 +11,7 @@
  */
 
 import { useQueryStates as clientUseQueryStates } from '../client/use-query-states.js';
-import { fromSchema, isStandardSchema, isCodec, validateSync } from '../schema-bridge.js';
+import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
 import type { Codec } from '../codec.js';
 
@@ -165,9 +165,43 @@ export type { StandardSchemaV1 } from '../schema-bridge.js';
 // Type-level helpers
 // ---------------------------------------------------------------------------
 
-/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */
+/**
+ * Extract a Standard Schema's declared *input* type from its optional
+ * `~standard.types` property (part of the Standard Schema spec; Zod, Valibot,
+ * and ArkType all declare it at the type level). Falls back to `never` when
+ * the schema doesn't declare types (e.g. hand-written schemas): with no
+ * metadata we can't know whether the schema handles `undefined`, so InferField
+ * widens conservatively rather than risk a type lie.
+ */
+type InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }
+  ? [NonNullable<TS>] extends [{ input: infer I }]
+    ? I
+    : never
+  : never;
+
+/**
+ * Infer the output type from either a SearchParamCodec or a StandardSchemaV1.
+ *
+ * Schemas whose input type rejects `undefined` (e.g. bare `z.string()`, whose
+ * input is `string`) are implicitly optional: the URL might not contain the
+ * param, and fromSchema returns `undefined` when the schema rejects absent
+ * input and has no default. The output type widens to `T | undefined` so the
+ * type doesn't lie. Schemas that accept `undefined` input (`.optional()`,
+ * `.default()`) keep their declared output type.
+ *
+ * Limitation: `z.coerce.*` schemas declare input `unknown`, which accepts
+ * `undefined` at the type level — so a coerce schema without `.default()`
+ * keeps its narrow output type even though absent input yields `undefined`
+ * at runtime. Add `.default()` to coerce schemas for accurate types.
+ */
 export type InferField<V> =
-  V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+  V extends SearchParamCodec<infer T>
+    ? T
+    : V extends StandardSchemaV1<infer T>
+      ? undefined extends InferSchemaInput<V>
+        ? T
+        : T | undefined
+      : never;
 
 /** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */
 export type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;
@@ -198,9 +232,17 @@ function normalizeRaw(
  * Compute the serialized default value for a codec. Used for
  * default-omission: when serialize(value) === serialize(parse(undefined)),
  * the field is omitted from the URL.
+ *
+ * Codecs are documented to return a default rather than throw, but a
+ * hand-written codec that throws on absent input must not turn definition
+ * into a crash — treat its default as null (nothing to omit).
  */
 function getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {
-  return codec.serialize(codec.parse(undefined));
+  try {
+    return codec.serialize(codec.parse(undefined));
+  } catch {
+    return null;
+  }
 }
 
 // isStandardSchema and isCodec are imported from schema-bridge.ts.
@@ -218,22 +260,11 @@ function resolveField(
     return { codec: value, urlKey: value.urlKey };
   }
 
-  // Auto-detect Standard Schema
+  // Auto-detect Standard Schema. Schemas that reject undefined input and
+  // have no default are implicitly optional: fromSchema returns undefined
+  // for absent params, and InferField widens the output type to
+  // T | undefined. design/23-search-params.md §"Implicit Optionality"
   if (isStandardSchema(value)) {
-    // Validate that the schema handles absent params (undefined input).
-    // Search params are optional — the URL might not contain the param.
-    // If the schema rejects undefined and has no default, the codec would
-    // return `undefined as T`, making the type lie. Catch this at definition
-    // time instead. design/23-search-params.md §"Default Validation"
-    const absentCheck = validateSync(value, undefined);
-    if (absentCheck.issues) {
-      throw new Error(
-        `[timber] defineSearchParams: field '${fieldName}' has no default value and rejects undefined input.\n` +
-          `  Search params are optional — the URL might not contain ?${fieldName}=anything.\n` +
-          `  Add .default() to your schema: z.coerce.number().int().min(1).default(1)\n` +
-          `  Or use .optional() if the field is truly optional.`
-      );
-    }
     return { codec: fromSchema(value) };
   }
 
@@ -244,25 +275,6 @@ function resolveField(
   );
 }
 
-/**
- * Validate that all codecs handle absent params (parse(undefined) doesn't throw).
- * Catches schemas that throw on missing input. `undefined` and `null` are both
- * valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).
- */
-function validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>): void {
-  for (const [key, codec] of Object.entries(codecMap)) {
-    try {
-      codec.parse(undefined);
-    } catch {
-      throw new Error(
-        `[timber] defineSearchParams: field '${key}' throws when the param is absent.\n` +
-          `  Search params are optional — the URL might not contain ?${key}=anything.\n` +
-          `  Add .default() or .optional() to your schema, or wrap with withDefault().`
-      );
-    }
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -297,9 +309,13 @@ function validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>):
  * )
  * ```
  */
-export function defineSearchParams<T extends Record<string, unknown>>(
-  schema: StandardSchemaV1<T> & { shape: Record<string, StandardSchemaV1<unknown>> }
-): SearchParamsDefinition<T>;
+export function defineSearchParams<
+  S extends StandardSchemaV1<Record<string, unknown>> & {
+    shape: Record<string, StandardSchemaV1<unknown>>;
+  },
+>(
+  schema: S
+): SearchParamsDefinition<{ [K in keyof S['shape'] & string]: InferField<S['shape'][K]> }>;
 
 /**
  * Overload: accept a map of codecs and/or Standard Schema objects.
@@ -357,9 +373,6 @@ function defineSearchParamsFromMap(
     }
   }
 
-  // Validate that all codecs handle absent params
-  validateDefaults(resolvedCodecs);
-
   return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, urlKeys);
 }
 
@@ -484,11 +497,6 @@ function buildDefinition<T extends Record<string, unknown>>(
     // Merge URL keys: base keys + new codec urlKeys from withUrlKey
     const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };
 
-    // Same definition-time guard as defineSearchParams — a throw-on-absent
-    // codec added via extend() gets the friendly guidance error, not a
-    // crash on first parse (TIM-1066).
-    validateDefaults(combinedCodecs as Record<string, SearchParamCodec<unknown>>);
-
     return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);
   }
 
@@ -515,8 +523,6 @@ function buildDefinition<T extends Record<string, unknown>>(
       }
     }
 
-    validateDefaults(pickedCodecs);
-
     return buildDefinition<Pick<T, K>>(
       pickedCodecs as unknown as CodecMap<Pick<T, K>>,
       pickedUrlKeys