@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/src/client/use-pathname.ts

@@ -4,48 +4,38 @@
  * Returns the pathname portion of the current URL (e.g. '/dashboard/settings').
  * 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 only subscribed to popstate events — meaning usePathname()
- * did NOT re-render on forward navigation (pushState). The context approach
- * fixes this: pathname updates in the same render pass as the new tree.
+ * One unconditional read of NavigationContext, on every side (TIM-1425):
  *
- * During SSR, reads the request pathname from the SSR ALS context
- * (populated by ssr-entry.ts) instead of window.location.
+ * - In the browser, the provider wraps the RSC payload in renderRoot(), so
+ *   the pathname updates in the same render pass as the new tree.
+ * - During SSR, the wrapper chain mounts the same provider with the request's
+ *   pathname (TIM-1424), so this is the identical code path — no ALS read,
+ *   no fallback tiers.
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts, which has a throwing stub
+ *   (TIM-1420).
+ * - Called outside a component entirely, React itself throws its
+ *   invalid-hook-call error — loud, not guessed-at from window.location.
  *
  * Compatible with Next.js's `usePathname()` from `next/navigation`.
  */
 
-import { getSsrData } from './ssr-data.ts';
 import { useNavigationContext } from './navigation-context.ts';
 
 /**
  * Read the current URL pathname.
  *
- * On the client, reads from NavigationContext (provided by
- * NavigationProvider in renderRoot). During SSR, reads from the
- * ALS-backed SSR data context. Falls back to window.location.pathname
- * when called outside a React component (e.g., in tests).
+ * Throws when no NavigationProvider is above the caller (a component rendered
+ * outside the timber app — in tests, render inside the timber providers).
  */
 export function usePathname(): string {
-  // Try reading from NavigationContext (client-side, inside React tree).
-  // During SSR, no NavigationProvider is mounted, so this returns null.
-  try {
-    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path
-    const navContext = useNavigationContext();
-    if (navContext !== null) {
-      return navContext.pathname;
-    }
-  } catch {
-    // No React dispatcher available (called outside a component).
-    // Fall through to SSR/fallback below.
+  const nav = useNavigationContext();
+  if (nav === null) {
+    throw new Error(
+      '[timber] usePathname() was called outside the timber app tree ' +
+        '(no NavigationProvider found). In tests, render the component ' +
+        'inside the timber providers.'
+    );
   }
-
-  // SSR path: read from ALS-backed SSR data context.
-  const ssrData = getSsrData();
-  if (ssrData) return ssrData.pathname ?? '/';
-
-  // Final fallback: window.location (tests, edge cases).
-  if (typeof window !== 'undefined') return window.location.pathname;
-  return '/';
+  return nav.pathname;
 }

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

@@ -4,25 +4,23 @@
  * Returns a read-only URLSearchParams instance reflecting the current
  * 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 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.
+ * One unconditional read of NavigationContext, on every side (TIM-1425):
  *
- * 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.
+ * - In the browser, the provider is updated atomically with the RSC tree
+ *   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.
+ * - During SSR, the wrapper chain mounts the same provider carrying the
+ *   request's RAW query string (TIM-1424), so repeated keys
+ *   (`?tag=a&tag=b`) survive — the collapsed record the ALS context holds
+ *   cannot represent them.
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts (TIM-1420).
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the
  * local copy but do NOT affect the URL — use the router or nuqs for that.
  *
- * During SSR, reads the request search params from the SSR ALS context
- * (populated by ssr-entry.ts) instead of window.location.
- *
  * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 
@@ -42,24 +40,28 @@ function getSearchParams(search: string): URLSearchParams {
 /**
  * Read the current URL search params.
  *
+ * Throws when no NavigationProvider is above the caller.
+ *
  * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 export function useSearchParams(): URLSearchParams {
-  try {
-    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path
-    const navContext = useNavigationContext();
-    if (navContext !== null) {
-      return getSearchParams(navContext.search);
-    }
-  } catch {
-    // No React dispatcher available (called outside a component).
+  const nav = useNavigationContext();
+  if (nav === null) {
+    throw new Error(
+      '[timber] useSearchParams() was called outside the timber app tree ' +
+        '(no NavigationProvider found). In tests, render the component ' +
+        'inside the timber providers.'
+    );
   }
-
-  // SSR path: read from ALS-backed SSR data context.
-  const ssrData = getSsrData();
-  if (ssrData) return new URLSearchParams(ssrData.searchParams);
-
-  // Final fallback: window.location (tests, edge cases).
-  if (typeof window !== 'undefined') return getSearchParams(window.location.search);
-  return new URLSearchParams();
+  // On the server, return a fresh instance per call. The module-level cache
+  // below exists to give client code stable identity for effect deps; on the
+  // server it would be shared mutable state across concurrent requests
+  // (design/13-security.md, "no global fallback state"). Both halves of the
+  // check matter: `window` is absent in a plain Node SSR render, and
+  // getSsrData() catches SSR environments that do define `window` (handleSsr
+  // always runs inside the ALS scope). Pinned by tests/ssr-provider-hooks.test.ts.
+  if (typeof window === 'undefined' || getSsrData()) {
+    return new URLSearchParams(nav.search);
+  }
+  return getSearchParams(nav.search);
 }

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

@@ -14,126 +14,39 @@
  * When the Routes interface is empty (no codegen yet), the generic
  * overload has `keyof Routes = never`, so only the fallback matches.
  *
- * During SSR, params are read from the ALS-backed SSR data context
- * (populated by ssr-entry.ts) to ensure correct per-request isolation
- * across concurrent requests with streaming Suspense.
- *
- * Reactivity: On the client, useParams() reads from ParamsContext, published
- * by the one provider the client renders above the merge point
- * (`PayloadRoot`). Params update atomically with the tree because they travel
- * on the same payload root — there is no separate channel that could be
- * seeded a render early or late (TIM-1294, TIM-1297).
- *
- * All mutable state is delegated to client/state.ts for singleton guarantees.
- * See design/18-build-system.md §"Singleton State Registry"
+ * One unconditional read of ParamsContext, on every side (TIM-1425):
+ *
+ * - In the browser, `PayloadRoot` publishes the payload's params above the
+ *   merge point on every render path. Params update atomically with the RSC
+ *   tree — no timing gap (TIM-1294, TIM-1297).
+ * - During SSR, the wrapper chain mounts the same `PayloadRoot`, fed the
+ *   `params` half of `splitPayloadRoot(root)` — the identical derivation
+ *   the browser performs at hydration (TIM-1424).
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts (TIM-1420).
+ * - Called outside a component entirely, React itself throws its
+ *   invalid-hook-call error.
+ *
+ * The module-level subscribe/notify machinery and the `currentParams`
+ * snapshot that used to back a fourth fallback tier are gone (TIM-1425):
+ * the provider is unconditional on every render path, so nothing read them.
  *
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
 import type { CoercedParams } from '../shared/param-value.ts';
 import type { Routes } from '../index.ts';
-import { getSsrData } from './ssr-data.ts';
-import {
-  currentParams,
-  currentSlotParams,
-  _setCurrentParams,
-  _setCurrentSlotParams,
-  paramsListeners,
-} from './state.ts';
-import { resolveSegmentParams, type SlotParamsRecord } from '../shared/slot-params.ts';
+import { resolveSegmentParams } from '../shared/slot-params.ts';
 import { useParamsContext } from './params-context.ts';
 
-// ---------------------------------------------------------------------------
-// Module-level subscribe/notify pattern — kept for backward compat and tests
-// ---------------------------------------------------------------------------
-
-/**
- * Subscribe to params changes.
- * Retained for backward compatibility with tests that verify the
- * subscribe/notify contract. On the client, useParams() reads from
- * NavigationContext instead.
- */
-export function subscribe(callback: () => void): () => void {
-  paramsListeners.add(callback);
-  return () => paramsListeners.delete(callback);
-}
-
-/**
- * Get the current params snapshot (module-level fallback).
- * Used by tests and by the hook when called outside a React component.
- */
-export function getSnapshot(): CoercedParams {
-  return currentParams;
-}
-
-// ---------------------------------------------------------------------------
-// Framework API — called by the segment router on each navigation
-// ---------------------------------------------------------------------------
-
-/**
- * Set the current route params in the module-level store.
- *
- * Called by the router on each navigation. This updates the fallback
- * snapshot used by tests and by the hook when called outside a React
- * component (no NavigationContext available).
- *
- * On the client, the primary reactivity path is NavigationContext —
- * the router calls setNavigationState() then renderRoot() which wraps
- * the element in NavigationProvider. setCurrentParams is still called
- * for the module-level fallback.
- *
- * During SSR, params are also available via getSsrData().params
- * (ALS-backed).
- */
-export function setCurrentParams(params: CoercedParams): void {
-  _setCurrentParams(params);
-}
-
-/**
- * Set the per-slot params snapshot in the module-level store.
- *
- * Paired with `setCurrentParams`: the router calls both on every navigation,
- * including with `null` when a response carries no slot params, so a slot's
- * params from the *previous* route cannot be read on the next one. Fill and
- * serve are paired; so are fill and clear. See TIM-1285.
- */
-export function setCurrentSlotParams(slotParams: SlotParamsRecord | null): void {
-  _setCurrentSlotParams(slotParams);
-}
-
-/**
- * Notify all legacy subscribers that params have changed.
- *
- * Retained for backward compatibility with tests. On the client,
- * the NavigationContext + renderRoot pattern replaces this — params
- * update atomically with the tree render, so explicit notification
- * is no longer needed.
- */
-export function notifyParamsListeners(): void {
-  for (const listener of paramsListeners) {
-    listener();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Public hook
-// ---------------------------------------------------------------------------
-
 /**
  * Read the current route's dynamic params.
  *
  * The optional `_route` argument exists only for TypeScript narrowing —
  * it does not affect the runtime return value.
  *
- * On the client, reads from ParamsContext, published by `PayloadRoot` above
- * everything the navigation renders. Params update atomically with the RSC
- * tree — no timing gap.
- *
- * During SSR, reads from the ALS-backed SSR data context to ensure
- * per-request isolation across concurrent requests with streaming Suspense.
- *
- * When called outside a React component (e.g., in test assertions),
- * falls back to the module-level snapshot.
+ * Throws when no `PayloadRoot` is above the caller (a component rendered
+ * outside the timber app — in tests, render inside the timber providers).
  *
  * @overload Typed — when a known segment path is passed, returns the
  *   exact params shape from the generated Routes interface.
@@ -144,25 +57,13 @@ export function useSegmentParams<R extends keyof Routes>(
 ): Routes[R] extends { segmentParams: infer P } ? P : CoercedParams;
 export function useSegmentParams(segmentPath?: string): CoercedParams;
 export function useSegmentParams(segmentPath?: string): CoercedParams {
-  // Try the client-owned provider first. It sits above everything a navigation
-  // renders, so any component on the page — initial document, full navigation,
-  // or a layout the server skipped — has one above it. Absent during SSR,
-  // where the ALS path below is the answer. When called outside a React
-  // component, useContext throws — caught below.
-  try {
-    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path
-    const paramsContext = useParamsContext();
-    if (paramsContext !== null) {
-      return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
-    }
-  } catch {
-    // No React dispatcher available (called outside a component).
-    // Fall through to module-level snapshot below.
+  const paramsContext = useParamsContext();
+  if (paramsContext === null) {
+    throw new Error(
+      '[timber] useSegmentParams() was called outside the timber app tree ' +
+        '(no params provider found). In tests, render the component inside ' +
+        'the timber providers.'
+    );
   }
-
-  // SSR path: read from ALS-backed SSR data context.
-  // Falls back to module-level currentParams for tests.
-  const ssrData = getSsrData();
-  if (ssrData) return resolveSegmentParams(ssrData.params, ssrData.slotParams, segmentPath);
-  return resolveSegmentParams(currentParams, currentSlotParams, segmentPath);
+  return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
 }

package/src/config-types.ts

@@ -288,6 +288,23 @@ export interface TimberUserConfig {
    * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
    */
   clientSegmentCache?: boolean;
+  /**
+   * Cache behavior configuration.
+   */
+  cache?: {
+    /**
+     * Promote the runtime-tier cache.component key-discipline warning to a
+     * hard error. When true, a cached component that reads request context
+     * (cookies, headers, searchParams) during a capture render throws
+     * instead of logging — the tainted payload is never cached.
+     *
+     * Default: false (structured error-level diagnostic, rate-limited per
+     * component). Recommended true for any app serving authenticated content.
+     *
+     * See design/45-cache-lifetimes.md §Enforcement.
+     */
+    strictKeyDiscipline?: boolean;
+  };
   topLoader?: {
     /** Whether the top-loader is enabled. Default: true. */
     enabled?: boolean;

package/src/config-validation.ts

@@ -46,6 +46,7 @@ const KNOWN_CONFIG_KEYS = {
   reactCompiler: true,
   sitemap: true,
   buildDir: true,
+  cache: true,
   clientSegmentCache: true,
   topLoader: true,
   budget: true,
@@ -195,6 +196,22 @@ export function validateConfig(config: TimberUserConfig): ConfigError[] {
     }
   }
 
+  // cache
+  if (config.cache != null && typeof config.cache === 'object') {
+    if (
+      config.cache.strictKeyDiscipline !== undefined &&
+      typeof config.cache.strictKeyDiscipline !== 'boolean'
+    ) {
+      errors.push({
+        field: 'cache.strictKeyDiscipline',
+        message: `cache.strictKeyDiscipline must be a boolean (got ${JSON.stringify(config.cache.strictKeyDiscipline)}).`,
+        value: config.cache.strictKeyDiscipline,
+        suggestion:
+          'Use cache: { strictKeyDiscipline: true } to promote key-discipline warnings to errors.',
+      });
+    }
+  }
+
   const MOVED_TO_CACHE_FILE = new Set(['cacheHandler', 'cdnPurge']);
 
   for (const key of Object.keys(config)) {

package/src/dev-tools/holding-server.ts

@@ -13,8 +13,10 @@
  *
  * The holding server is started in rootSync's config() hook (the
  * earliest Vite plugin lifecycle point where we know the port) and
- * closed in timber-dev-server's configureServer() hook (the last
- * plugin, right before Vite calls server.listen()).
+ * closed directly in timber-dev-server's configureServer() hook
+ * (the last plugin, fire-and-forget). configureServer runs during
+ * createServer(), well before Vite's port probe and bind, so the
+ * port is free by the time httpServerStart() runs. (TIM-1419)
  *
  * Browser requests (Accept: text/html) get the HTML holding page.
  * API requests (Accept: application/json) get a 503 JSON response.
@@ -29,10 +31,12 @@ import http from 'node:http';
 
 export interface HoldingServer {
   /**
-   * Start listening on the given port.
+   * Start listening on the given port and host.
+   * The host must match Vite's resolved `server.host` so the probe
+   * faithfully detects conflicts on the same address Vite will bind.
    * Returns the actual bound port (useful when port is 0 for OS assignment).
    */
-  listen(port: number): Promise<number>;
+  listen(port: number, host?: string): Promise<number>;
 
   /** Gracefully close the server and stop accepting connections. */
   close(): Promise<void>;
@@ -125,12 +129,13 @@ const HOLDING_PAGE_HTML = [
  * const holding = createHoldingServer();
  * await bindWithBump((p) => holding.listen(p), { startPort: 3000, autoBump: true });
  *
- * // In last plugin's configureServer() — wrap listen for seamless handoff
- * const originalListen = server.listen.bind(server);
- * server.listen = async (...args) => {
- *   await holding.close();
- *   return originalListen(...args);
- * };
+ * // In last plugin's configureServer() — close directly so Vite 8's
+ * // isPortAvailable() probe and httpServer.listen() both see a free
+ * // port. SO_REUSEADDR allows immediate rebind. (TIM-1419)
+ * if (ctx.holdingServer) {
+ *   ctx.holdingServer.close().catch(() => {});
+ *   ctx.holdingServer = null;
+ * }
  * ```
  */
 export function createHoldingServer(): HoldingServer {
@@ -163,10 +168,10 @@ export function createHoldingServer(): HoldingServer {
   });
 
   return {
-    listen(port: number): Promise<number> {
+    listen(port: number, host?: string): Promise<number> {
       return new Promise((resolve, reject) => {
         server.once('error', reject);
-        server.listen(port, () => {
+        server.listen(port, host, () => {
           server.removeListener('error', reject);
           const addr = server.address();
           const boundPort = typeof addr === 'object' && addr ? addr.port : port;
@@ -176,6 +181,12 @@ export function createHoldingServer(): HoldingServer {
     },
 
     close(): Promise<void> {
+      // Kill lingering keep-alive sockets immediately — the holding
+      // page's meta-refresh keeps browser connections alive, and
+      // server.close() waits for all sockets to drain before the
+      // 'close' event fires. Without this, the close can stall for
+      // the full keepAliveTimeout (~5s), blocking the port handoff.
+      server.closeAllConnections();
       return new Promise((resolve, reject) => {
         server.close((err) => {
           if (err) reject(err);

package/src/index.ts

@@ -343,6 +343,16 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // that closes the holding server never runs — starting it would
       // occupy the default port for the embedding's lifetime.
       const isMiddlewareMode = Boolean(userConfig.server?.middlewareMode);
+      // Resolve the host Vite will bind so the holding server probes the
+      // same address. Vite defaults to 'localhost' when server.host is
+      // unset; binding wildcard (no host) would mask conflicts on
+      // localhost due to SO_REUSEADDR address-family differences. TIM-1419.
+      const resolvedHost =
+        typeof userConfig.server?.host === 'string'
+          ? userConfig.server.host
+          : userConfig.server?.host === true
+            ? undefined
+            : 'localhost';
       if (command === 'serve' && !isPreview && !isMiddlewareMode) {
         ctx.holdingServer = createHoldingServer();
         const holdingRef = ctx.holdingServer;
@@ -350,7 +360,7 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
           configPort:
             typeof userConfig.server?.port === 'number' ? userConfig.server.port : undefined,
           envPort: process.env.PORT,
-          listen: (p) => holdingRef.listen(p),
+          listen: (p) => holdingRef.listen(p, resolvedHost),
         });
         if (!result.bound) {
           // Holding server failed to bind. Drop the reference so the
@@ -358,13 +368,17 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
           // never listening.
           ctx.holdingServer = null;
         }
-        if (result.bound || result.explicit) {
-          // When bound, use the probed port with strictPort so Vite
-          // doesn't re-bump. When unbound but explicit, still forward
-          // the port so Vite surfaces the conflict via strictPort.
-          // When unbound and implicit, skip — let Vite auto-bump.
+        if (result.bound) {
+          // Forward the probed port so Vite starts there. strictPort
+          // matches explicit — explicit ports fail loudly on a race
+          // between close and bind; implicit ones let Vite re-bump.
           resolvedDevPort = result.port;
           resolvedDevPortExplicit = result.explicit;
+        } else if (result.explicit) {
+          // Explicit port failed to bind (another process holds it).
+          // Forward it as the starting point but without strictPort
+          // so Vite auto-bumps to the next free port. TIM-1419.
+          resolvedDevPort = result.port;
         }
       } else if (command === 'serve' && isPreview) {
         // Preview mode: resolve the starting port from config/env/
@@ -431,10 +445,11 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // Dev/preview mode: set outDir so dev-time references are
       // consistent, and surface the resolved port to Vite.
       //
-      // For dev, we set strictPort: true so Vite uses exactly the port
-      // the holding server probed for — without strictPort, Vite would
-      // run its own auto-bump starting from `port`, which would skip
-      // straight past whatever holding-server-bumped port we picked.
+      // For dev with an explicit port, we set strictPort: true so Vite
+      // fails loudly on conflict. For auto-bumped (implicit) ports, we
+      // leave strictPort false so Vite can re-bump if the holding server's
+      // port becomes unavailable between close and bind (e.g., a second
+      // app instance starting on the same default port). TIM-1419.
       //
       // For `vite preview`, we set `preview.strictPort` based on
       // whether the user explicitly set the port. Implicit (default)
@@ -451,7 +466,7 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       if (resolvedDevPort != null) {
         if (!isPreview) {
           serverConfig.port = resolvedDevPort;
-          serverConfig.strictPort = true;
+          serverConfig.strictPort = resolvedDevPortExplicit;
         }
         previewConfig.port = resolvedDevPort;
         previewConfig.strictPort = resolvedDevPortExplicit;

package/src/plugins/dev-server.ts

@@ -118,7 +118,7 @@ export function timberDevServer(ctx: PluginContext): Plugin {
      * rewritten /index.html. Vite-internal and asset requests are
      * filtered out explicitly and passed through to Vite.
      */
-    configureServer(server: ViteDevServer) {
+    async configureServer(server: ViteDevServer) {
       // Ensure config files are in the watch set. Vite's watcher covers
       // the project root, but `server.watcher.add()` is a no-op for files
       // already watched, and ensures newly-created config files (e.g. from
@@ -191,19 +191,16 @@ export function timberDevServer(ctx: PluginContext): Plugin {
       // discover it. See design/47-module-environment-tooling.md §5.
       registerDevDiscovery(server.httpServer, ctx.root, server.config);
 
-      // Wrap server.listen() to close the holding server immediately
-      // before Vite binds the port — no gap where nothing is listening.
-      // The holding server was started in rootSync's config() hook to
-      // serve a loading page during initialization.
-      // See design/21-dev-server.md §"Startup Holding Server", TIM-665.
+      // Close the holding server and await the port release so Vite's
+      // port probe and bind see a free port. configureServer is awaited
+      // by Vite during createServer(), before startServer() runs
+      // isPortAvailable() and httpServer.listen().
+      // closeAllConnections() (in HoldingServer.close) kills keep-alive
+      // sockets from the meta-refresh page so close() resolves promptly.
+      // See design/21-dev-server.md §"Startup Holding Server", TIM-1419.
       if (ctx.holdingServer) {
-        const originalListen = server.listen.bind(server);
-        const holdingRef = ctx.holdingServer;
+        await ctx.holdingServer.close().catch(() => {});
         ctx.holdingServer = null;
-        server.listen = async (port?: number, isRestart?: boolean) => {
-          await holdingRef.close().catch(() => {});
-          return originalListen(port, isRestart);
-        };
       }
 
       // Log startup timing summary. configureServer runs on all plugins

package/src/plugins/entries.ts

@@ -159,6 +159,9 @@ function generateConfigModule(ctx: PluginContext): string {
     // Null in dev mode — HMR handles code updates without full reloads.
     deploymentId: ctx.deploymentId ?? null,
     clientSegmentCache: ctx.config.clientSegmentCache ?? false,
+    cache: {
+      strictKeyDiscipline: ctx.config.cache?.strictKeyDiscipline ?? false,
+    },
     // Browser log forwarding threshold — used by buildClientScripts to
     // decide whether /@vite/client is needed when clientJavascript is
     // disabled. See TIM-1152.

package/src/plugins/shims.ts

@@ -198,14 +198,15 @@ export function timberShims(_ctx: PluginContext): Plugin {
       const cleanId = stripJsExtension(id);
 
       // Check next/* shim map.
-      // In the client (browser) environment, next/navigation resolves to
-      // navigation-client.ts which only re-exports client hooks — not server
-      // functions like redirect() and deny(). This prevents server/primitives.ts
-      // from being pulled into the browser bundle.
+      // next/navigation resolves per environment (TIM-1420):
+      //   RSC    → navigation-rsc.ts    (throwing stubs — no useContext)
+      //   SSR    → navigation.ts        (real hooks + server functions)
+      //   client → navigation-client.ts (real hooks, no server imports)
       if (cleanId in SHIM_MAP) {
-        const env = envName(this);
-        if (env === 'client' && cleanId === 'next/navigation') {
-          return resolve(SHIMS_DIR, 'navigation-client.ts');
+        if (cleanId === 'next/navigation') {
+          const env = envName(this);
+          if (env === 'client') return resolve(SHIMS_DIR, 'navigation-client.ts');
+          if (env === 'rsc') return resolve(SHIMS_DIR, 'navigation-rsc.ts');
         }
         return SHIM_MAP[cleanId];
       }

package/src/plugins/static-build.ts

@@ -228,7 +228,11 @@ export class StaticOutputPaths {
    *   asked, not assumed. Folding unconditionally would reject `/Foo` beside
    *   `/foo` on Linux, where both are perfectly servable files.
    */
-  constructor(private readonly identity: FsIdentity = EXACT_FS_IDENTITY) {}
+  private readonly identity: FsIdentity;
+
+  constructor(identity: FsIdentity = EXACT_FS_IDENTITY) {
+    this.identity = identity;
+  }
 
   /** The identity under which the filesystem will compare this path. */
   private key(relPath: string): string {
@@ -309,10 +313,10 @@ export class StaticSiteWriter {
   readonly contentTypes: Record<string, string> = {};
   private readonly paths: StaticOutputPaths;
 
-  constructor(
-    private readonly staticDir: string,
-    identity: FsIdentity = EXACT_FS_IDENTITY
-  ) {
+  private readonly staticDir: string;
+
+  constructor(staticDir: string, identity: FsIdentity = EXACT_FS_IDENTITY) {
+    this.staticDir = staticDir;
     this.paths = new StaticOutputPaths(identity);
   }