@timber-js/app 0.2.0-alpha.165 → 0.2.0-alpha.167

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/plugins/adapter-build.ts

@@ -83,6 +83,7 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
         }
 
         const adapterConfig: TimberConfig = {
+          root: ctx.root,
           output: ctx.config.output ?? 'server',
           clientJavascriptDisabled: ctx.clientJavascript.disabled,
           manifestInit,

package/src/plugins/cache.ts

@@ -1,13 +1,13 @@
 /**
  * timber-cache-transform — Vite plugin that injects stable callsite IDs
- * into `cache()` calls imported from `@timber-js/app/cache`.
+ * into `cache.data()` calls imported from `@timber-js/app/cache`.
  *
  * Detected callsite forms (TIM-1054):
- *   - named imports, including aliases: `import { cache as c }` + `c(fn, opts)`
- *   - namespace imports: `import * as ns` + `ns.cache(fn, opts)`
+ *   - named imports, including aliases: `import { cache as c }` + `c.data(fn, opts)`
+ *   - namespace imports: `import * as ns` + `ns.cache.data(fn, opts)`
  * Forms a per-module transform cannot trace — local variable aliases
  * (`const c = cache`), user re-export wrapper modules, computed access
- * (`ns['cache']`) — fall back to the runtime fnId derived from
+ * (`cache['data']`) — fall back to the runtime fnId derived from
  * fnv1a(fn.toString()) (see cache/timber-cache.ts), which is deterministic
  * across instances and cold starts of the same build. Without either
  * mechanism, an ordinal counter would collide across instances with a shared
@@ -15,8 +15,8 @@
  * data to another.
  *
  * The plugin transforms:
- *   cache(fn, opts)      →  cache(fn, opts, "stable-id")
- *   ns.cache(fn, opts)   →  ns.cache(fn, opts, "stable-id")
+ *   cache.data(fn, opts)          →  cache.data(fn, opts, "stable-id")
+ *   ns.cache.data(fn, opts)       →  ns.cache.data(fn, opts, "stable-id")
  *
  * where stable-id =
  *   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
@@ -34,9 +34,9 @@
  * unrelated edits, while a changed call gets a fresh ID — which is exactly
  * when invalidation is wanted.
  *
- * The enclosing-statement text is included so that byte-identical cache()
+ * The enclosing-statement text is included so that byte-identical cache.data()
  * calls in different scopes — e.g. two factory helpers that each `return
- * cache(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
+ * cache.data(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
  * enclosing declarations differ by name/body even when the call spans are
  * identical. Without it, a source-order occurrence counter alone would shift
  * when an identical span is inserted above, reassigning IDs across deploys.
@@ -75,41 +75,56 @@ import type {
 } from './callsite-ast.js';
 
 /**
- * Is this callee a reference to the imported `cache` function — either a bare
- * identifier bound by a named import, or `ns.cache` on a namespace import?
- * Computed access (`ns['cache']`) is deliberately not matched; it falls back
+ * Is this callee a `cache.data(...)` call? Matches two forms:
+ *   - Named import: `cache.data(fn, opts)` where `cache` is the imported binding
+ *   - Namespace import: `ns.cache.data(fn, opts)` where `ns` is the namespace
+ * Computed access (`cache['data']`) is deliberately not matched; it falls back
  * to the runtime fnId derivation.
  */
-function isCacheCallee(callee: PositionedNode, bindings: ImportBindings): boolean {
-  if (callee.type === 'Identifier') {
-    return bindings.named.has((callee as IdentifierNode).name);
+function isCacheDataCallee(callee: PositionedNode, bindings: ImportBindings): boolean {
+  if (callee.type !== 'MemberExpression') return false;
+  const member = callee as unknown as MemberExpressionNode;
+  if (member.computed) return false;
+  if (member.property.type !== 'Identifier' || (member.property as IdentifierNode).name !== 'data')
+    return false;
+
+  const obj = member.object;
+  // Named import: `cache.data(...)` — obj is the imported `cache` identifier
+  if (obj.type === 'Identifier') {
+    return bindings.named.has((obj as IdentifierNode).name);
   }
-  if (callee.type === 'MemberExpression') {
-    const member = callee as unknown as MemberExpressionNode;
+  // Namespace import: `ns.cache.data(...)` — obj is `ns.cache`
+  if (obj.type === 'MemberExpression') {
+    const outer = obj as unknown as MemberExpressionNode;
     return (
-      !member.computed &&
-      member.object.type === 'Identifier' &&
-      bindings.namespaces.has((member.object as IdentifierNode).name) &&
-      member.property.type === 'Identifier' &&
-      (member.property as IdentifierNode).name === 'cache'
+      !outer.computed &&
+      outer.object.type === 'Identifier' &&
+      bindings.namespaces.has((outer.object as IdentifierNode).name) &&
+      outer.property.type === 'Identifier' &&
+      (outer.property as IdentifierNode).name === 'cache'
     );
   }
   return false;
 }
 
 /**
- * Extract the local binding name that a cache callee resolves to — the
- * identifier for named imports, or the namespace object for `ns.cache()`.
+ * Extract the local binding name that a cache.data callee resolves to — the
+ * `cache` identifier for named imports, or the namespace object for `ns.cache.data()`.
  */
 function calleeBindingName(callee: PositionedNode, bindings: ImportBindings): string | null {
-  if (callee.type === 'Identifier') {
-    const name = (callee as IdentifierNode).name;
+  if (callee.type !== 'MemberExpression') return null;
+  const member = callee as unknown as MemberExpressionNode;
+  const obj = member.object;
+  // Named import: `cache.data(...)` — binding is `cache`
+  if (obj.type === 'Identifier') {
+    const name = (obj as IdentifierNode).name;
     return bindings.named.has(name) ? name : null;
   }
-  if (callee.type === 'MemberExpression') {
-    const member = callee as unknown as MemberExpressionNode;
-    if (member.object.type === 'Identifier') {
-      const name = (member.object as IdentifierNode).name;
+  // Namespace import: `ns.cache.data(...)` — binding is `ns`
+  if (obj.type === 'MemberExpression') {
+    const outer = obj as unknown as MemberExpressionNode;
+    if (outer.object.type === 'Identifier') {
+      const name = (outer.object as IdentifierNode).name;
       return bindings.namespaces.has(name) ? name : null;
     }
   }
@@ -182,7 +197,7 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
           stmt,
           (call) =>
             call.arguments.length === 2 &&
-            isCacheCallee(call.callee, cacheBindings) &&
+            isCacheDataCallee(call.callee, cacheBindings) &&
             !isCalleeShadowed(call),
           calls
         );

package/src/routing/scanner.ts

@@ -232,6 +232,13 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     // See design/16-metadata.md §"Metadata Routes"
     const metaInfo = classifyMetadataRoute(entry);
     if (metaInfo) {
+      if (!metaInfo.nestable && node.segmentName !== '') {
+        throw new Error(
+          `Build error: '${name}' is a root-only metadata convention and must be in the app root directory.\n` +
+            `  File: ${fullPath}\n` +
+            `  Move this file to the app root (not a route group or nested segment).`
+        );
+      }
       if (!node.metadataRoutes) {
         node.metadataRoutes = {};
       }

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;
     },