@timber-js/app 0.2.0-alpha.146 → 0.2.0-alpha.148

package/src/client/browser-entry/post-hydration.ts

@@ -11,9 +11,8 @@
  * See design/19-client-navigation.md §"History Stack"
  */
 
-import { setCurrentParams } from '#client-internal';
 import type { RouterInstance } from '#client-internal';
-import { setNavigationState } from '../navigation-context.js';
+import { getNavigationState } from '../navigation-context.js';
 import type { NavigationApiController } from '../navigation-api.js';
 import { getScrollY } from './scroll.js';
 
@@ -35,9 +34,14 @@ export function setupPostHydration({
   // Store the initial page in the history stack so back-button works
   // after the first navigation. We store the decoded RSC element so
   // back navigation can replay it instantly without a server fetch.
+  // Params were captured from the server-embedded __timber_params by
+  // runPreHydration() — without them on the entry, the cached replay on
+  // back-navigation would normalize params to {} and wipe every
+  // useSegmentParams() consumer on the initial page (TIM-1037).
   router.historyStack.push(window.location.pathname + window.location.search, {
     payload: initialElement,
     headElements: null, // SSR already set the correct head
+    params: getNavigationState().params,
   });
 
   // Initialize scroll state for the initial entry.
@@ -58,19 +62,6 @@ export function setupPostHydration({
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
 
-  // If the hydration path was skipped (no RSC payload), populate the
-  // fallback params from server embed here.
-  const lateTimberParams = (self as unknown as Record<string, unknown>).__timber_params;
-  if (lateTimberParams && typeof lateTimberParams === 'object') {
-    setCurrentParams(lateTimberParams as Record<string, string | string[]>);
-    setNavigationState({
-      params: lateTimberParams as Record<string, string | string[]>,
-      pathname: window.location.pathname,
-      search: window.location.search,
-    });
-    delete (self as unknown as Record<string, unknown>).__timber_params;
-  }
-
   // Register popstate handler for back/forward navigation.
   // When Navigation API is active, the navigate event covers traversals —
   // popstate is a no-op. When unavailable, popstate handles back/forward.

package/src/client/browser-entry/router-init.ts

@@ -14,7 +14,11 @@ import type { RouterDeps, RouterInstance } from '#client-internal';
 import type { NavigationState } from '#client-internal';
 import { applyHeadElements } from '../head.js';
 import { TimberNuqsAdapter } from '../nuqs-adapter.js';
-import { NavigationProvider } from '../navigation-context.js';
+import {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from '../navigation-context.js';
 import { transitionRender, navigateTransition } from '../navigation-root.js';
 import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.js';
 import {
@@ -54,10 +58,96 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
   // very first client navigation (before any wrapPayload call).
   let currentPayload: unknown = options?.initialElement ?? null;
 
+  // ─── History API Patch ──────────────────────────────────────────
+  // Patch pushState/replaceState to detect external URL changes (nuqs
+  // shallow updates, replaceUrl, third-party libraries). When the router
+  // itself calls pushState/replaceState, it sets a flag so the patch
+  // skips the sync — the router already updates NavigationContext.
+  //
+  // On Navigation API browsers, the navigate event catches most URL
+  // changes. The patch is defense-in-depth and the primary mechanism
+  // for History API-only browsers (older Safari/Firefox).
+  const ROUTER_HISTORY_FLAG = Symbol.for('__timber_router_history_update');
+  const gFlags = globalThis as Record<symbol, boolean>;
+
+  const originalPushState = window.history.pushState.bind(window.history);
+  const originalReplaceState = window.history.replaceState.bind(window.history);
+
+  /**
+   * Sync NavigationContext.search after a shallow URL update. Called by
+   * the Navigation API shallow handler and the History API patch.
+   *
+   * @param search — the new search string. The Navigation API path passes
+   *   this from event.destination.url (window.location hasn't committed
+   *   yet when the navigate listener fires). The History API patch omits
+   *   it, reading window.location.search (already committed by the time
+   *   the patched pushState/replaceState returns).
+   *
+   * Bails when search is unchanged (scroll saves, no-ops, dual-fire).
+   * Re-wraps currentPayload with updated NavigationProvider and commits
+   * via transitionRender (startTransition — non-blocking).
+   */
+  function syncShallowSearch(search?: string): void {
+    const currentSearch = search ?? window.location.search;
+    const navState = getNavigationState();
+    if (currentSearch === navState.search) return;
+    if (!currentPayload) return;
+
+    const newNavState: NavigationState = {
+      params: navState.params,
+      pathname: navState.pathname,
+      search: currentSearch,
+    };
+    setNavigationState(newNavState);
+
+    const withNav = createElement(
+      NavigationProvider,
+      { value: newNavState },
+      currentPayload as React.ReactNode
+    );
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
+    transitionRender(wrapped);
+  }
+
+  window.history.pushState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalPushState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
+  window.history.replaceState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalReplaceState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
   const deps: RouterDeps = {
     fetch: (url, init) => window.fetch(url, init),
-    pushState: (data, unused, url) => window.history.pushState(data, unused, url),
-    replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
+    pushState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.pushState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
+    replaceState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.replaceState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
     navigationApiActive: useNavApi,
     scrollTo: (x, y) => {
       // Scroll the document viewport.
@@ -94,6 +184,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     // navState is passed explicitly by the router — no temporal coupling
     // with getNavigationState().
     renderRoot: (element: unknown, navState: NavigationState) => {
+      currentPayload = element;
       const withNav = createElement(
         NavigationProvider,
         { value: navState },
@@ -183,6 +274,10 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
         // Back/forward — delegate to the router's popstate handler.
         await router.handlePopState(url, scrollY, signal);
       },
+      onShallowNavigate: (destinationUrl: string) => {
+        const search = new URL(destinationUrl).search;
+        syncShallowSearch(search);
+      },
     });
 
     // Wire the router-navigating flag into RouterDeps.

package/src/client/error-boundary.tsx

@@ -255,7 +255,21 @@ export class TimberErrorBoundary extends Component<
 
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
+      // Status-code file boundaries (404.tsx, 4xx.tsx, …) get the documented
+      // 4xx props. error.tsx boundaries (no status filter) get their
+      // documented { error, digest, reset } contract — plus the deny extras
+      // for dual-shape implementations. Without the error prop, an error.tsx
+      // reading error.message crashes on deny fall-through. See TIM-1081.
+      if (this.props.status != null) {
+        return createElement(this.props.fallbackComponent as never, {
+          status: parsed.status,
+          dangerouslyPassData: parsed.data,
+        });
+      }
       return createElement(this.props.fallbackComponent as never, {
+        error,
+        digest: null,
+        reset: this.reset,
         status: parsed.status,
         dangerouslyPassData: parsed.data,
       });

package/src/client/error-reconstituter.tsx

@@ -33,6 +33,9 @@ export interface SerializableError {
  * - digest: plain JSON or null
  * - reset: undefined (only meaningful on client after boundary catch)
  * - component: client module reference (RSC Flight serializes as opaque ref)
+ * - status / dangerouslyPassData: set only when error.tsx serves a deny()
+ *   as the last entry in the 4xx fallback chain — forwarded so dual-shape
+ *   error.tsx implementations can branch on the deny status (TIM-1081)
  */
 interface ErrorReconstituterProps {
   error: SerializableError;
@@ -42,7 +45,11 @@ interface ErrorReconstituterProps {
     error: Error;
     digest: { code: string; data: unknown } | null;
     reset: (() => void) | undefined;
+    status?: number;
+    dangerouslyPassData?: unknown;
   }>;
+  status?: number;
+  dangerouslyPassData?: unknown;
 }
 
 /**
@@ -54,6 +61,8 @@ export function ErrorReconstituter({
   digest,
   reset,
   component,
+  status,
+  dangerouslyPassData,
 }: ErrorReconstituterProps): ReactNode {
   // Reconstitute a real Error so instanceof checks work in user code
   const error = Object.assign(new Error(serialized.message), {
@@ -61,5 +70,10 @@ export function ErrorReconstituter({
     ...(serialized.stack != null ? { stack: serialized.stack } : {}),
   });
 
-  return createElement(component, { error, digest, reset });
+  return createElement(component, {
+    error,
+    digest,
+    reset,
+    ...(status != null ? { status, dangerouslyPassData } : {}),
+  });
 }

package/src/client/history.ts

@@ -10,7 +10,12 @@ export interface HistoryEntry {
   payload: unknown;
   /** Resolved head elements for this page (title, meta tags). Null for SSR'd initial page. */
   headElements?: HeadElement[] | null;
-  /** Route params for this page (for useParams). Null for SSR'd initial page. */
+  /**
+   * Route params for this page (for useSegmentParams). Every entry that can
+   * be replayed must carry them — the initial SSR entry gets them from the
+   * server-embedded __timber_params, navigation entries from X-Timber-Params,
+   * and revalidation overwrites preserve the current state (TIM-1037).
+   */
   params?: Record<string, string | string[]> | null;
 }
 
@@ -23,13 +28,8 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Supports two keying modes:
- * - **URL-keyed** (default): entries keyed by pathname + search.
- *   Used with the History API fallback.
- * - **Entry-key + URL**: when the Navigation API is available,
- *   entries can also be stored by Navigation entry key for
- *   disambiguation of duplicate URLs in the history stack.
- *   Falls back to URL lookup when entry key is not found.
+ * Entries are keyed by pathname + search. Used with the History API
+ * fallback and the Navigation API.
  *
  * Scroll positions are stored in history.state or Navigation API entry
  * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
@@ -39,26 +39,12 @@ export interface HistoryEntry {
  */
 export class HistoryStack {
   private entries = new Map<string, HistoryEntry>();
-  /** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
-  private entryKeyMap = new Map<string, HistoryEntry>();
 
-  push(url: string, entry: HistoryEntry, entryKey?: string): void {
+  push(url: string, entry: HistoryEntry): void {
     this.entries.set(url, entry);
-    if (entryKey) {
-      this.entryKeyMap.set(entryKey, entry);
-    }
   }
 
-  /**
-   * Get an entry. When an entry key is provided (Navigation API),
-   * tries the entry-key map first for accurate disambiguation of
-   * duplicate URLs, then falls back to URL lookup.
-   */
-  get(url: string, entryKey?: string): HistoryEntry | undefined {
-    if (entryKey) {
-      const byKey = this.entryKeyMap.get(entryKey);
-      if (byKey) return byKey;
-    }
+  get(url: string): HistoryEntry | undefined {
     return this.entries.get(url);
   }
 

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