@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/src/client/navigation-api.ts

@@ -18,7 +18,6 @@
  */
 
 import type { NavigationApi, NavigateEvent } from './navigation-api-types.js';
-import { consumeNavLinkMetadata } from './nav-link-store.js';
 import { isHardNavigating } from './navigation-root.js';
 
 // ─── Feature Detection ───────────────────────────────────────────
@@ -55,8 +54,8 @@ export function getNavigationApi(): NavigationApi | null {
 export interface NavigationApiCallbacks {
   /**
    * Handle a push/replace navigation intercepted by the Navigation API.
-   * This covers both Link <a> clicks (user-initiated, with metadata from
-   * nav-link-store) and external navigations (plain <a> tags, programmatic).
+   * This covers both Link <a> clicks (user-initiated) and external
+   * navigations (plain <a> tags, programmatic).
    * The Navigation API handles the URL update via event.intercept().
    */
   onExternalNavigate: (
@@ -69,6 +68,14 @@ export interface NavigationApiCallbacks {
    * the traversal and delegates to us for RSC replay/fetch.
    */
   onTraverse: (url: string, scrollY: number, signal: AbortSignal) => Promise<void>;
+
+  /**
+   * Called when a shallow URL update is intercepted (e.g., nuqs with
+   * shallow: true, or replaceUrl). The URL has already been committed —
+   * this callback syncs NavigationContext.search so useSearchParams()
+   * reflects the new value without a full router navigation.
+   */
+  onShallowNavigate?: (url: string) => void;
 }
 
 /**
@@ -187,6 +194,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
         focusReset: 'manual',
         scroll: 'manual',
       });
+      callbacks.onShallowNavigate?.(event.destination.url);
       return;
     }
 
@@ -239,11 +247,8 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
         },
       });
     } else if (event.navigationType === 'push' || event.navigationType === 'replace') {
-      // Push/replace — either a Link <a> click (with metadata in
-      // nav-link-store) or an external navigation (plain <a>, programmatic).
-      // Consume link metadata if present — tells us scroll preference
-      // and which Link component to track pending state for.
-      const linkMeta = consumeNavLinkMetadata();
+      // Push/replace — a Link <a> click or an external navigation
+      // (plain <a> tag, programmatic).
 
       // Save the departing page's scroll position BEFORE event.intercept()
       // commits the URL change. Once intercept() is called, currentEntry
@@ -273,7 +278,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
           await callbacks.onExternalNavigate(url + destUrl.hash, {
             replace: event.navigationType === 'replace',
             signal: event.signal,
-            scroll: linkMeta?.scroll,
+            scroll: undefined,
           });
         },
       });

package/src/client/navigation-context.ts

@@ -176,7 +176,7 @@ export function getNavigationState(): NavigationState {
  * Separate context for the in-flight navigation URL. Provided by
  * NavigationRoot (urgent useState), consumed by usePendingNavigation
  * and TopLoader. Per-link pending state uses useOptimistic instead
- * (see link-pending-store.ts).
+ * (see design/19-client-navigation.md §"Per-Link Pending State").
  *
  * Uses globalThis via Symbol.for for the same reason as NavigationContext
  * above — the bundler may duplicate this module across chunks, and module-
@@ -225,23 +225,3 @@ export function PendingNavigationProvider({
   }
   return createElement(ctx.Provider, { value }, children);
 }
-
-// ---------------------------------------------------------------------------
-// Navigation API transition state (optional progressive enhancement)
-// ---------------------------------------------------------------------------
-
-/**
- * Check if the browser's Navigation API has an active transition.
- *
- * When the Navigation API is available and a navigation has been intercepted
- * via event.intercept(), `navigation.transition` is non-null until the
- * handler resolves. This provides browser-native progress tracking that
- * can be used alongside the existing pendingUrl mechanism.
- *
- * Returns false when Navigation API is unavailable or no transition is active.
- */
-export function hasNativeNavigationTransition(): boolean {
-  if (typeof window === 'undefined') return false;
-  const nav = (window as unknown as { navigation?: { transition?: unknown } }).navigation;
-  return nav?.transition != null;
-}

package/src/client/navigation-root.tsx

@@ -324,14 +324,6 @@ export function navigateTransition(
   return perform().then(() => {});
 }
 
-/**
- * Check if the NavigationRoot is mounted and ready for renders.
- * Used by browser-entry.ts to guard against renders before hydration.
- */
-export function isNavigationRootReady(): boolean {
-  return _transitionRender !== null;
-}
-
 /**
  * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
  *

package/src/client/router.ts

@@ -778,16 +778,21 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * Called on hover of <Link prefetch> elements.
    */
   function prefetch(url: string): void {
+    // Strip fragment — it's client-only and would swallow the _rsc cache-bust
+    // param into the hash. The hash-less key also matches navigate()'s fetchUrl.
+    const hashIndex = url.indexOf('#');
+    const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+
     // Don't prefetch if already cached
-    if (prefetchCache.get(url) !== undefined) return;
-    if (historyStack.has(url)) return;
+    if (prefetchCache.get(fetchUrl) !== undefined) return;
+    if (historyStack.has(fetchUrl)) return;
 
     // Fire-and-forget fetch
     const stateTree = segmentCache.serializeStateTree();
-    void fetchRscPayload(url, deps, stateTree).then(
+    void fetchRscPayload(fetchUrl, deps, stateTree).then(
       (result) => {
         result.decodePromise?.catch(() => {});
-        prefetchCache.set(url, result);
+        prefetchCache.set(fetchUrl, result);
       },
       () => {
         // Prefetch failure is non-fatal — navigation will fetch fresh
@@ -813,15 +818,20 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Revalidation payloads are already resolved (no Flight thenable),
       // so no segment merging is needed — just cache and render.
       const currentUrl = deps.getCurrentUrl();
-      historyStack.push(currentUrl, {
-        payload: element,
-        headElements,
-      });
 
       // Revalidation doesn't change params/pathname — preserve current state.
       // DO NOT call updateNavigationState(null, ...) here: that normalizes
       // params to {}, clearing dynamic route params on every action response.
       const navState = getNavigationState();
+
+      // Keep params on the overwritten entry — dropping them would make
+      // away-and-back navigation replay this page with params normalized
+      // to {} (TIM-1037).
+      historyStack.push(currentUrl, {
+        payload: element,
+        headElements,
+        params: navState.params,
+      });
       renderPayload(element, navState);
       applyHead(headElements);
     },

package/src/client/rsc-fetch.ts

@@ -61,10 +61,15 @@ function generateCacheBustId(): string {
  * Append a `_rsc=<id>` query parameter to the URL.
  * Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
  * for RSC navigation requests and signals that this is an RSC fetch.
+ *
+ * Strips any #fragment before appending — fragments are client-only and
+ * fetch() discards them, so _rsc would land inside the hash and be lost.
  */
 function appendRscParam(url: string): string {
-  const separator = url.includes('?') ? '&' : '?';
-  return `${url}${separator}_rsc=${generateCacheBustId()}`;
+  const hashIndex = url.indexOf('#');
+  const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const separator = urlWithoutHash.includes('?') ? '&' : '?';
+  return `${urlWithoutHash}${separator}_rsc=${generateCacheBustId()}`;
 }
 
 // ─── Deployment ID ───────────────────────────────────────────────

package/src/client/use-search-params.ts

@@ -5,11 +5,16 @@
  * URL's query string. Updates when client-side navigation changes the URL.
  *
  * On the client, reads from NavigationContext which is updated atomically
- * with the RSC tree render. This replaces the previous useSyncExternalStore
- * approach which read window.location.search directly — causing React to
- * detect external store tearing during transitions and fall back to
- * synchronous rendering (renderRootSync instead of renderRootConcurrent),
- * blocking the main thread and freezing animations.
+ * with the RSC tree render during full navigations, AND by
+ * syncShallowSearch() for shallow URL updates (nuqs shallow: true,
+ * replaceUrl, or any external pushState/replaceState that changes the
+ * query string). See router-init.ts.
+ *
+ * This replaces the previous useSyncExternalStore approach which read
+ * window.location.search directly — causing React to detect external
+ * store tearing during transitions and fall back to synchronous rendering
+ * (renderRootSync instead of renderRootConcurrent), blocking the main
+ * thread and freezing animations.
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the

package/src/config-validation.ts

@@ -20,6 +20,39 @@ export interface ConfigError {
   suggestion?: string;
 }
 
+// ─── Known config keys ──────────────────────────────────────────────────────
+
+// `satisfies Record<keyof TimberUserConfig, true>` makes this drift-proof:
+// adding a key to TimberUserConfig without listing it here is a compile
+// error, so validateConfig can never reject a documented option (TIM-1066).
+const KNOWN_CONFIG_KEYS = {
+  output: true,
+  debug: true,
+  clientJavascript: true,
+  adapter: true,
+  cacheHandler: true,
+  allowedOrigins: true,
+  csrf: true,
+  limits: true,
+  actions: true,
+  forms: true,
+  pageExtensions: true,
+  slowRequestMs: true,
+  renderTimeoutMs: true,
+  devBrowserLogs: true,
+  dev: true,
+  serverTiming: true,
+  appDir: true,
+  mdx: true,
+  actionEncryption: true,
+  reactCompiler: true,
+  sitemap: true,
+  buildDir: true,
+  topLoader: true,
+} satisfies Record<keyof TimberUserConfig, true>;
+
+const knownKeys = new Set<string>(Object.keys(KNOWN_CONFIG_KEYS));
+
 // ─── Validation ─────────────────────────────────────────────────────────────
 
 /**
@@ -147,31 +180,6 @@ export function validateConfig(config: TimberUserConfig): ConfigError[] {
     }
   }
 
-  // Unknown top-level keys
-  const knownKeys = new Set([
-    'output',
-    'debug',
-    'clientJavascript',
-    'adapter',
-    'cacheHandler',
-    'allowedOrigins',
-    'csrf',
-    'limits',
-    'pageExtensions',
-    'slowRequestMs',
-    'renderTimeoutMs',
-    'devBrowserLogs',
-    'dev',
-    'serverTiming',
-    'appDir',
-    'mdx',
-    'actionEncryption',
-    'reactCompiler',
-    'sitemap',
-    'buildDir',
-    'topLoader',
-  ]);
-
   for (const key of Object.keys(config)) {
     if (!knownKeys.has(key)) {
       errors.push({

package/src/cookies/define-cookie.ts

@@ -24,6 +24,7 @@ import type { ClientCookieOptions } from '../client/use-cookie.js';
 
 import type { Codec } from '../codec.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
+import { resolveCodecOrSchema } from '../schema-bridge.js';
 
 /**
  * A codec that converts between string cookie values and typed values.
@@ -87,7 +88,6 @@ export interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {
 // Schema: fromSchema is a pure function — safe in all environments.
 
 import { getCookieJar } from '@timber-js/app/server';
-import { fromSchema } from '../schema-bridge.js';
 import {
   useCookie as useRawCookie,
   notifyCookieChange,
@@ -147,23 +147,7 @@ function deleteClientCookie(name: string, options?: ClientCookieOptions): void {
 // ─── Standard Schema Auto-Detection ───────────────────────────────────────
 
 function resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {
-  // If it has parse + serialize, it's already a Codec
-  if (
-    typeof (codecOrSchema as Codec<T>).parse === 'function' &&
-    typeof (codecOrSchema as Codec<T>).serialize === 'function'
-  ) {
-    return codecOrSchema as CookieCodec<T>;
-  }
-
-  // Auto-detect Standard Schema
-  if (typeof codecOrSchema === 'object' && codecOrSchema !== null && '~standard' in codecOrSchema) {
-    return fromSchema(codecOrSchema as StandardSchemaV1<unknown>) as CookieCodec<T>;
-  }
-
-  throw new Error(
-    '[timber] defineCookie: codec must be a Codec<T> (with parse/serialize methods) ' +
-      'or a Standard Schema object (Zod, Valibot, ArkType).'
-  );
+  return resolveCodecOrSchema('codec', codecOrSchema, 'search') as CookieCodec<T>;
 }
 
 // ─── Factory ──────────────────────────────────────────────────────────────

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

@@ -37,7 +37,11 @@ export interface DevErrorHmrOptions {
  * so the auto-reload WebSocket connects to the correct endpoint.
  */
 export function extractHmrOptions(config: {
-  server?: { hmr?: { protocol?: string; host?: string; port?: number; path?: string } | boolean };
+  server?: {
+    hmr?:
+      | { protocol?: string; host?: string; port?: number; clientPort?: number; path?: string }
+      | boolean;
+  };
   webSocketToken?: string;
 }): DevErrorHmrOptions | undefined {
   const hmr = config.server?.hmr;
@@ -46,7 +50,7 @@ export function extractHmrOptions(config: {
   const opts: DevErrorHmrOptions = {
     protocol: hmrOpts.protocol,
     host: hmrOpts.host,
-    port: hmrOpts.port,
+    port: hmrOpts.clientPort || hmrOpts.port,
     path: hmrOpts.path,
     token: config.webSocketToken,
   };

package/src/dev-tools/hydration-overlay.ts

@@ -0,0 +1,158 @@
+/**
+ * Hydration mismatch diff overlay — dev-only.
+ *
+ * Parses React 19's structured diff from hydration error messages and
+ * renders a color-coded + Client / - Server diff in a dismissible overlay.
+ *
+ * See design/21-dev-server.md §"Error Overlay"
+ */
+
+const REACT_HYDRATION_LINK = 'https://react.dev/link/hydration-mismatch';
+
+const HYDRATION_PATTERNS = [
+  /^In HTML, (.+?) cannot be a child of <(.+?)>\./,
+  /^In HTML, (.+?) cannot be a descendant of <(.+?)>\./,
+  /^In HTML, text nodes cannot be a child of <(.+?)>\./,
+  /^In HTML, whitespace text nodes cannot be a child of <(.+?)>\./,
+  /Hydration failed because the server rendered (text|HTML) didn't match the client\./,
+  /A tree hydrated but some attributes of the server rendered HTML didn't match the client properties/,
+];
+
+export function isHydrationError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const msg = (error as { message?: string }).message;
+  if (typeof msg !== 'string') return false;
+  return HYDRATION_PATTERNS.some((re) => re.test(msg));
+}
+
+interface ParsedHydrationError {
+  message: string;
+  diff: string | null;
+}
+
+function parseHydrationError(msg: string): ParsedHydrationError {
+  const hasComponentStackDiff = [
+    /^In HTML, (.+?) cannot be a child of <(.+?)>\.(.*)\nThis will cause a hydration error\.(.*)/,
+    /^In HTML, (.+?) cannot be a descendant of <(.+?)>\.\nThis will cause a hydration error\.(.*)/,
+    /^In HTML, text nodes cannot be a child of <(.+?)>\.\nThis will cause a hydration error\./,
+    /^In HTML, whitespace text nodes cannot be a child of <(.+?)>\./,
+  ].some((re) => re.test(msg));
+
+  if (hasComponentStackDiff) {
+    const [message, diffLog = ''] = msg.split('\n\n');
+    const diff = diffLog.trim();
+    return { message: message.trim(), diff: diff || null };
+  }
+
+  const [before, after] = msg.split(REACT_HYDRATION_LINK);
+  if (after !== undefined && after.length > 1) {
+    const lines: string[] = [];
+    for (const line of after.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed === '' || trimmed.startsWith('at ')) continue;
+      lines.push(line);
+    }
+    return { message: before.trim(), diff: lines.join('\n') || null };
+  }
+
+  return { message: msg.trim(), diff: null };
+}
+
+let overlayEl: HTMLDivElement | null = null;
+let errors: ParsedHydrationError[] = [];
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function renderDiffHtml(diff: string): string {
+  return diff
+    .split('\n')
+    .map((line) => {
+      const trimmed = line.trimStart();
+      if (trimmed.startsWith('+')) {
+        return `<span style="color:#4ade80;display:block">${escapeHtml(line)}</span>`;
+      }
+      if (trimmed.startsWith('-')) {
+        return `<span style="color:#f87171;display:block">${escapeHtml(line)}</span>`;
+      }
+      return `<span style="color:#a1a1aa;display:block">${escapeHtml(line)}</span>`;
+    })
+    .join('');
+}
+
+function render(): void {
+  if (errors.length === 0) {
+    if (overlayEl) {
+      overlayEl.remove();
+      overlayEl = null;
+    }
+    return;
+  }
+
+  if (!overlayEl) {
+    overlayEl = document.createElement('div');
+    overlayEl.setAttribute('data-timber-hydration-overlay', '');
+    document.body.appendChild(overlayEl);
+  }
+
+  const count = errors.length;
+  const errorsHtml = errors
+    .map(
+      (err, i) => `
+      <div style="margin-bottom:${i < count - 1 ? '16px' : '0'};padding-bottom:${i < count - 1 ? '16px' : '0'};border-bottom:${i < count - 1 ? '1px solid #333' : 'none'}">
+        <div style="color:#fbbf24;font-weight:600;margin-bottom:8px">${escapeHtml(err.message)}</div>
+        ${
+          err.diff
+            ? `<div style="margin-top:8px">
+                <div style="display:flex;gap:16px;margin-bottom:6px;font-size:11px">
+                  <span><span style="color:#4ade80">+</span> Client</span>
+                  <span><span style="color:#f87171">-</span> Server</span>
+                </div>
+                <pre style="margin:0;padding:10px;background:#1a1a1a;border-radius:4px;overflow-x:auto;font-size:12px;line-height:1.5">${renderDiffHtml(err.diff)}</pre>
+              </div>`
+            : ''
+        }
+      </div>`
+    )
+    .join('');
+
+  overlayEl.innerHTML = `
+    <div style="position:fixed;inset:0;background:rgba(0,0,0,0.6);z-index:2147483646;display:flex;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" data-timber-hydration-backdrop>
+      <div style="background:#18181b;color:#e4e4e7;border:1px solid #333;border-radius:8px;max-width:720px;width:90vw;max-height:80vh;display:flex;flex-direction:column;box-shadow:0 8px 32px rgba(0,0,0,0.5)">
+        <div style="display:flex;justify-content:space-between;align-items:center;padding:12px 16px;border-bottom:1px solid #333">
+          <div style="display:flex;align-items:center;gap:8px">
+            <span style="background:#dc2626;color:#fff;padding:2px 8px;border-radius:4px;font-size:11px;font-weight:700;text-transform:uppercase">Hydration Mismatch</span>
+            ${count > 1 ? `<span style="color:#71717a;font-size:12px">${count} errors</span>` : ''}
+          </div>
+          <button data-timber-hydration-close style="background:none;border:1px solid #333;color:#a1a1aa;cursor:pointer;padding:4px 10px;border-radius:4px;font-size:12px;line-height:1">Dismiss</button>
+        </div>
+        <div style="padding:16px;overflow-y:auto;font-size:13px;line-height:1.6">
+          ${errorsHtml}
+        </div>
+      </div>
+    </div>`;
+
+  overlayEl.querySelector('[data-timber-hydration-close]')?.addEventListener('click', dismiss);
+  overlayEl.querySelector('[data-timber-hydration-backdrop]')?.addEventListener('click', (e) => {
+    if ((e.target as HTMLElement).hasAttribute('data-timber-hydration-backdrop')) dismiss();
+  });
+}
+
+function dismiss(): void {
+  errors = [];
+  render();
+}
+
+export function showHydrationError(error: unknown): void {
+  if (!error || typeof error !== 'object') return;
+  const msg = (error as { message?: string }).message;
+  if (typeof msg !== 'string') return;
+  const parsed = parseHydrationError(msg);
+  errors.push(parsed);
+  render();
+}

package/src/dev-tools/index.ts

@@ -8,7 +8,6 @@
  * - 404-page: self-contained HTML 404 page
  * - terminal: boxed terminal error output
  * - logger: structured request tree logger
- * - warnings: dev-mode footgun warnings
  * - browser-logs: forward browser console to server
  * - logs: forward server console to browser
  * - holding-server: startup holding server
@@ -64,21 +63,6 @@ export {
   type DevLoggerConfig,
 } from './logger.js';
 
-// Dev-mode warnings
-export {
-  warnSuspenseWrappingChildren,
-  warnDenyInSuspense,
-  warnRedirectInSuspense,
-  warnRedirectInAccess,
-  warnStaticRequestApi,
-  warnSlowSlotWithoutSuspense,
-  setViteServer,
-  WarningId,
-  type DevWarningConfig,
-  _resetWarnings,
-  _getEmitted,
-} from './warnings.js';
-
 // Browser log forwarding
 export {
   timberDevBrowserLogs,
@@ -94,3 +78,6 @@ export { createHoldingServer, type HoldingServer } from './holding-server.js';
 
 // OTEL instrumentation
 export { instrumentDevFetch, DevSpanProcessor, type DevFetchCleanup } from './instrumentation.js';
+
+// Hydration mismatch overlay (client-side, dev-only)
+export { isHydrationError, showHydrationError } from './hydration-overlay.js';