@timber-js/app 0.2.0-alpha.36 → 0.2.0-alpha.38

package/src/server/rsc-entry/index.ts

@@ -65,6 +65,7 @@ import {
   createDebugChannelSink,
   escapeHtml,
   isRscPayloadRequest,
+  type DebugComponentEntry,
 } from './helpers.js';
 import { parseClientStateTree } from '#/server/state-tree-diff.js';
 import { buildRscPayloadResponse } from './rsc-payload.js';
@@ -91,18 +92,35 @@ function resolveServerTimingMode(
 
 // Dev-only pipeline error handler, set by the dev server after import.
 // In production this is always undefined — no overhead.
-let _devPipelineErrorHandler: ((error: Error, phase: string) => void) | undefined;
+// The third argument provides RSC debug component data (from the Flight
+// debug channel) when available — used by the error overlay to show the
+// server component tree context for render errors.
+let _devPipelineErrorHandler:
+  | ((error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void)
+  | undefined;
 
 /**
  * Set the dev pipeline error handler.
  *
  * Called by the dev server after importing this module to wire pipeline
  * errors into the Vite browser error overlay. No-op in production.
+ *
+ * The handler receives an optional third argument with RSC debug component
+ * info — component names, environments, and stack frames from the Flight
+ * debug channel. This is only populated for render-phase errors.
  */
-export function setDevPipelineErrorHandler(handler: (error: Error, phase: string) => void): void {
+export function setDevPipelineErrorHandler(
+  handler: (error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void
+): void {
   _devPipelineErrorHandler = handler;
 }
 
+// Dev-only: holds a getter for the current request's RSC debug components.
+// Updated on each renderRscStream call so the onPipelineError callback can
+// include component tree context for render-phase errors. This is request-
+// scoped by convention — each renderRoute call sets it before returning.
+let _lastDebugComponentsGetter: (() => DebugComponentEntry[]) | undefined;
+
 /**
  * Create the RSC request handler from the route manifest.
  *
@@ -231,7 +249,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     serverTiming: resolveServerTimingMode(runtimeConfig, isDev),
     onPipelineError: isDev
       ? (error: Error, phase: string) => {
-          if (_devPipelineErrorHandler) _devPipelineErrorHandler(error, phase);
+          if (_devPipelineErrorHandler) {
+            // For render-phase errors, include RSC debug component data
+            // from the Flight debug channel (if available from the current request).
+            const debugComponents =
+              phase === 'render' && _lastDebugComponentsGetter
+                ? _lastDebugComponentsGetter()
+                : undefined;
+            _devPipelineErrorHandler(error, phase, debugComponents);
+          }
         }
       : undefined,
     renderFallbackError: (error, req, responseHeaders) =>
@@ -441,7 +467,11 @@ async function renderRoute(
 
   // Render to RSC Flight stream with signal tracking.
   const _rscStart = performance.now();
-  const { rscStream, signals } = renderRscStream(element, _req);
+  const { rscStream, signals, getDebugComponents } = renderRscStream(element, _req);
+
+  // Store the debug components getter so onPipelineError can include
+  // component tree context for render-phase errors (dev mode only).
+  _lastDebugComponentsGetter = getDebugComponents;
   recordTiming({
     name: 'rsc-init',
     dur: Math.round(performance.now() - _rscStart),

package/src/server/rsc-entry/rsc-payload.ts

@@ -103,9 +103,17 @@ export async function buildRscPayloadResponse(
   }
 
   // Extract the first chunk from the race result.
-  // If the signal won the race, read the first chunk now (the stream
-  // was already cancelled above, but we need a firstRead shape below).
-  const firstRead = first.type === 'data' ? first.chunk : await reader.read();
+  // If the signal won the race but neither redirect nor deny was detected
+  // (edge case), cancel the reader immediately rather than issuing a bare
+  // read() that could hang forever if the RSC stream has stalled.
+  // See TIM-519.
+  let firstRead: ReadableStreamReadResult<Uint8Array>;
+  if (first.type === 'data') {
+    firstRead = first.chunk;
+  } else {
+    await reader.cancel();
+    firstRead = { done: true, value: undefined };
+  }
 
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.

package/src/server/rsc-entry/rsc-stream.ts

@@ -16,8 +16,14 @@ import { logRenderError } from '#/server/logger.js';
 import { DenySignal, RedirectSignal, RenderError } from '#/server/primitives.js';
 import { checkAndWarnRscPropError } from '#/server/rsc-prop-warnings.js';
 
-import { createDebugChannelSink, isAbortError } from './helpers.js';
+import {
+  createDebugChannelSink,
+  createDebugChannelCollector,
+  isAbortError,
+  type DebugComponentEntry,
+} from './helpers.js';
 import { isDebug } from '#/server/debug.js';
+import { isDevMode } from '#/server/debug.js';
 
 /**
  * Mutable signal state captured during RSC rendering.
@@ -40,6 +46,8 @@ export interface RenderSignals {
 export interface RscStreamResult {
   rscStream: ReadableStream<Uint8Array> | undefined;
   signals: RenderSignals;
+  /** Dev-only: server component debug info from the Flight debug channel. */
+  getDebugComponents?: () => DebugComponentEntry[];
 }
 
 /**
@@ -62,6 +70,10 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
 
   let rscStream: ReadableStream<Uint8Array> | undefined;
 
+  // In dev mode, collect debug channel data for the error overlay.
+  // In production, use the discard sink (no overhead).
+  const debugChannel = isDevMode() ? createDebugChannelCollector() : createDebugChannelSink();
+
   try {
     rscStream = renderToReadableStream(
       element,
@@ -132,7 +144,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           }
           logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
         },
-        debugChannel: createDebugChannelSink(),
+        debugChannel,
       },
       {
         onClientReference(info: { id: string; name: string; deps: unknown }) {
@@ -160,5 +172,14 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
     }
   }
 
-  return { rscStream, signals };
+  return {
+    rscStream,
+    signals,
+    // Expose the debug channel collector's getComponents in dev mode.
+    // The caller can retrieve component tree info when handling errors.
+    getDebugComponents:
+      'getComponents' in debugChannel
+        ? (debugChannel as { getComponents: () => DebugComponentEntry[] }).getComponents
+        : undefined,
+  };
 }

package/src/server/slot-resolver.ts

@@ -45,13 +45,12 @@ async function loadComponent(loader: {
  */
 async function renderDefaultFallback(
   slotNode: ManifestSegmentNode,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement | null> {
   if (!slotNode.default) return null;
   const DefaultComp = await loadComponent(slotNode.default);
   if (!DefaultComp) return null;
-  return h(DefaultComp, { params: paramsPromise });
+  return h(DefaultComp, {});
 }
 
 // ─── Segment Tree Matching ──────────────────────────────────────────────────
@@ -153,7 +152,6 @@ function walkSegmentTree(
 export async function resolveSlotElement(
   slotNode: ManifestSegmentNode,
   match: RouteMatch,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn,
   interception?: InterceptionContext
 ): Promise<React.ReactElement | null> {
@@ -174,7 +172,7 @@ export async function resolveSlotElement(
       // degrade to default.tsx or null — not crash the page. This matches
       // Next.js behavior. See design/02-rendering-pipeline.md
       // §"Slot Access Failure = Graceful Degradation"
-      const denyFallback = await renderDefaultFallback(slotNode, paramsPromise, h);
+      const denyFallback = await renderDefaultFallback(slotNode, h);
 
       // Wrap the slot page to catch DenySignal (from notFound() or deny())
       // at the component level. This prevents the signal from reaching the
@@ -192,23 +190,21 @@ export async function resolveSlotElement(
         }
       };
 
-      let element: React.ReactElement = h(SafeSlotPage, {
-        params: paramsPromise,
-      });
+      let element: React.ReactElement = h(SafeSlotPage, {});
 
       // Wrap with error boundaries and layouts from intermediate slot segments
       // (everything between slot root and leaf). Process innermost-first, same
       // order as route-element-builder.ts handles main segments. The slot root
       // (index 0) is handled separately after the access gate below.
-      element = await wrapWithIntermediateSegments(slotMatch.chain, element, paramsPromise, h);
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h);
 
       // Wrap in SlotAccessGate if slot root has access.ts.
       // On denial: denied.tsx → default.tsx → null (graceful degradation).
       // See design/04-authorization.md §"Slot-Level Auth".
-      element = await wrapWithAccessGate(slotNode, element, paramsPromise, h);
+      element = await wrapWithAccessGate(slotNode, element, h);
 
       // Wrap with slot root's layout (outermost, outside access gate)
-      element = await wrapWithLayout(slotNode, element, paramsPromise, h);
+      element = await wrapWithLayout(slotNode, element, h);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -231,7 +227,7 @@ export async function resolveSlotElement(
   }
 
   // No matching page — render default.tsx fallback
-  return renderDefaultFallback(slotNode, paramsPromise, h);
+  return renderDefaultFallback(slotNode, h);
 }
 
 // ─── Element Wrapping Helpers ───────────────────────────────────────────────
@@ -244,13 +240,12 @@ export async function resolveSlotElement(
 async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement> {
   for (let i = chain.length - 1; i > 0; i--) {
     const seg = chain[i];
     element = await wrapSegmentWithErrorBoundaries(seg, element, h);
-    element = await wrapWithLayout(seg, element, paramsPromise, h);
+    element = await wrapWithLayout(seg, element, h);
   }
   return element;
 }
@@ -261,13 +256,12 @@ async function wrapWithIntermediateSegments(
 async function wrapWithLayout(
   node: ManifestSegmentNode,
   element: React.ReactElement,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement> {
   if (!node.layout) return element;
   const Layout = await loadComponent(node.layout);
   if (!Layout) return element;
-  return h(Layout, { params: paramsPromise, children: element });
+  return h(Layout, { children: element });
 }
 
 /**
@@ -277,7 +271,6 @@ async function wrapWithLayout(
 async function wrapWithAccessGate(
   slotNode: ManifestSegmentNode,
   element: React.ReactElement,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement> {
   if (!slotNode.access) return element;
@@ -295,12 +288,10 @@ async function wrapWithAccessGate(
   // Extract slot name from the directory name (strip @ prefix)
   const slotName = slotNode.segmentName?.replace(/^@/, '') ?? '';
 
-  const defaultFallback = await renderDefaultFallback(slotNode, paramsPromise, h);
-  const params = await paramsPromise;
+  const defaultFallback = await renderDefaultFallback(slotNode, h);
 
   return h(SlotAccessGate, {
     accessFn,
-    params,
     DeniedComponent,
     slotName,
     createElement: h,

package/src/server/ssr-entry.ts

@@ -243,12 +243,15 @@ export async function handleSsr(
           PassThrough,
         } = _nodeStreamImports;
 
+        const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
+
         let nodeHtmlStream: import('node:stream').Readable;
         try {
           nodeHtmlStream = await renderSsrNodeStream(wrappedElement, {
             bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
             deferSuspenseFor: navContext.deferSuspenseFor,
             signal: navContext.signal,
+            renderTimeoutMs,
           });
         } catch (renderError) {
           console.error(
@@ -266,7 +269,9 @@ export async function handleSsr(
         // element is <html>, so no framework-level doctype prepend needed.
         const errorHandler = createNodeErrorHandler(navContext.signal);
         const headInjector = createNodeHeadInjector(navContext.headHtml);
-        const flightInjector = createNodeFlightInjector(navContext.rscStream);
+        const flightInjector = createNodeFlightInjector(navContext.rscStream, {
+          renderTimeoutMs,
+        });
 
         const output = new PassThrough();
         pipeline(nodeHtmlStream, errorHandler, headInjector, flightInjector, output).catch(() => {
@@ -289,12 +294,14 @@ export async function handleSsr(
       }
 
       // Web Streams path (CF Workers / fallback)
+      const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
       let htmlStream: ReadableStream<Uint8Array>;
       try {
         htmlStream = await renderSsrStream(wrappedElement, {
           bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
           deferSuspenseFor: navContext.deferSuspenseFor,
           signal: navContext.signal,
+          renderTimeoutMs,
         });
       } catch (renderError) {
         console.error(
@@ -312,7 +319,7 @@ export async function handleSsr(
       // Inject metadata into <head>, then interleave RSC payload chunks
       // into the body as they arrive from the tee'd RSC stream.
       let outputStream = injectHead(htmlStream, navContext.headHtml);
-      outputStream = injectRscPayload(outputStream, navContext.rscStream);
+      outputStream = injectRscPayload(outputStream, navContext.rscStream, renderTimeoutMs);
       const _pipelineEnd = performance.now();
 
       navContext._ssrTimings = {

package/src/server/ssr-render.ts

@@ -24,6 +24,7 @@ import type { ReactNode } from 'react';
 import { renderToReadableStream } from 'react-dom/server';
 
 import { formatSsrError } from './error-formatter.js';
+import { createRenderTimeout, RenderTimeoutError } from './render-timeout.js';
 
 /**
  * Inline script that injects <meta name="robots" content="noindex"> into <head>.
@@ -105,7 +106,12 @@ try {
  */
 export async function renderSsrStream(
   element: ReactNode,
-  options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
+  options?: {
+    bootstrapScriptContent?: string;
+    deferSuspenseFor?: number;
+    signal?: AbortSignal;
+    renderTimeoutMs?: number;
+  }
 ): Promise<ReadableStream<Uint8Array>> {
   return renderViaReadableStream(element, options);
 }
@@ -130,17 +136,25 @@ export const useNodeStreams = _useNodeStreams;
  */
 export async function renderSsrNodeStream(
   element: ReactNode,
-  options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
+  options?: {
+    bootstrapScriptContent?: string;
+    deferSuspenseFor?: number;
+    signal?: AbortSignal;
+    renderTimeoutMs?: number;
+  }
 ): Promise<import('node:stream').Readable> {
   const signal = options?.signal;
   const deferMs = options?.deferSuspenseFor;
+  const timeoutMs = options?.renderTimeoutMs;
 
   return new Promise<import('node:stream').Readable>((resolve, reject) => {
     const passthrough = new _PassThrough!();
 
     let allReadyResolve: (() => void) | null = null;
-    const allReady = new Promise<void>((r) => {
-      allReadyResolve = r;
+    let allReadyReject: ((reason?: unknown) => void) | null = null;
+    const allReady = new Promise<void>((resolve, reject) => {
+      allReadyResolve = resolve;
+      allReadyReject = reject;
     });
     allReady.catch(() => {});
 
@@ -164,6 +178,10 @@ export async function renderSsrNodeStream(
       },
 
       onShellError(error: unknown) {
+        // Reject allReady so the render timeout is cancelled.
+        // Without this, a pre-shell failure leaves the timer
+        // running for the full timeout window.
+        allReadyReject?.(error);
         reject(error);
       },
 
@@ -173,6 +191,9 @@ export async function renderSsrNodeStream(
       },
     });
 
+    // Wire abort to both request signal AND render timeout.
+    // If the client stays connected but a downstream fetch hangs,
+    // the timeout ensures abort() is eventually called.
     if (signal) {
       if (signal.aborted) {
         abort();
@@ -180,6 +201,28 @@ export async function renderSsrNodeStream(
         signal.addEventListener('abort', () => abort(), { once: true });
       }
     }
+
+    if (timeoutMs && timeoutMs > 0) {
+      const renderTimeout = createRenderTimeout(timeoutMs, signal);
+      renderTimeout.signal.addEventListener(
+        'abort',
+        () => {
+          console.error(
+            `[timber] SSR render timed out after ${timeoutMs}ms — aborting. ` +
+              'A Suspense component or downstream fetch may be hanging.'
+          );
+          abort(renderTimeout.signal.reason);
+        },
+        { once: true }
+      );
+      // Cancel the timeout when the render completes OR on pre-shell
+      // failure. Without the catch branch, onShellError → reject()
+      // would leave the timer running for the full timeout window.
+      allReady.then(
+        () => renderTimeout.cancel(),
+        () => renderTimeout.cancel()
+      );
+    }
   });
 }
 
@@ -199,21 +242,59 @@ export function nodeReadableToWeb(
 
 async function renderViaReadableStream(
   element: ReactNode,
-  options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
+  options?: {
+    bootstrapScriptContent?: string;
+    deferSuspenseFor?: number;
+    signal?: AbortSignal;
+    renderTimeoutMs?: number;
+  }
 ): Promise<ReadableStream<Uint8Array>> {
   const signal = options?.signal;
-  const stream = await renderToReadableStream(element, {
-    bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
-    signal,
-    onError(error: unknown) {
-      if (isAbortError(error) || signal?.aborted) return;
-      console.error('[timber] SSR render error:', formatSsrError(error));
-    },
-  });
+  const timeoutMs = options?.renderTimeoutMs;
+
+  // If a render timeout is configured, create a combined signal that
+  // fires on either request abort OR timeout — whichever comes first.
+  let renderTimeout: import('./render-timeout.js').RenderTimeout | null = null;
+  let effectiveSignal = signal;
+  if (timeoutMs && timeoutMs > 0) {
+    renderTimeout = createRenderTimeout(timeoutMs, signal);
+    effectiveSignal = renderTimeout.signal;
+  }
+
+  let stream: Awaited<ReturnType<typeof renderToReadableStream>>;
+  try {
+    stream = await renderToReadableStream(element, {
+      bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
+      signal: effectiveSignal,
+      onError(error: unknown) {
+        if (isAbortError(error) || effectiveSignal?.aborted) return;
+        if (error instanceof RenderTimeoutError) {
+          console.error(
+            `[timber] SSR render timed out after ${timeoutMs}ms — aborting. ` +
+              'A Suspense component or downstream fetch may be hanging.'
+          );
+          return;
+        }
+        console.error('[timber] SSR render error:', formatSsrError(error));
+      },
+    });
+  } catch (error) {
+    // Pre-shell failure (e.g. RSC stream error). Cancel the render
+    // timeout so it doesn't leak a timer + abort callback for the
+    // full timeout window. Under repeated pre-shell failures this
+    // would accumulate unnecessary timers.
+    renderTimeout?.cancel();
+    throw error;
+  }
 
   // Prevent unhandled promise rejection from streaming-phase errors.
   stream.allReady.catch(() => {});
 
+  // Cancel the render timeout once allReady resolves (render completed).
+  if (renderTimeout) {
+    stream.allReady.then(() => renderTimeout!.cancel()).catch(() => renderTimeout!.cancel());
+  }
+
   // deferSuspenseFor hold: delay the first read so React can resolve
   // fast-completing Suspense boundaries before we read the shell HTML.
   // See design/05-streaming.md §"deferSuspenseFor"

package/src/server/tree-builder.ts

@@ -46,8 +46,13 @@ export type SlotElements = Map<string, ReactElement>;
 export interface TreeBuilderConfig {
   /** The matched segment chain from root to leaf. */
   segments: SegmentNode[];
-  /** Route params extracted by the matcher (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
+  /**
+   * Route params extracted by the matcher (catch-all segments produce string[]).
+   * @deprecated Params are now accessed via rawSegmentParams() from ALS.
+   * This field is kept for backward compatibility but is no longer used
+   * by the tree builder itself.
+   */
+  params?: Record<string, string | string[]>;
   /** Loads a route file's module. */
   loadModule: ModuleLoader;
   /** React.createElement or equivalent. */
@@ -76,7 +81,6 @@ export interface TreeBuilderConfig {
  */
 export interface AccessGateProps {
   accessFn: (ctx: { params: Record<string, string | string[]> }) => unknown;
-  params: Record<string, string | string[]>;
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
@@ -102,7 +106,6 @@ export interface AccessGateProps {
  */
 export interface SlotAccessGateProps {
   accessFn: (ctx: { params: Record<string, string | string[]> }) => unknown;
-  params: Record<string, string | string[]>;
   /** The denied.tsx component (not a pre-built element). null if no denied.tsx exists. */
   DeniedComponent: ((...args: unknown[]) => unknown) | null;
   /** Slot directory name without @ prefix (e.g. "admin", "sidebar"). */
@@ -149,7 +152,7 @@ export interface TreeBuildResult {
  * Parallel slots are resolved at each layout level and composed as named props.
  */
 export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult> {
-  const { segments, params, loadModule, createElement, errorBoundaryComponent } = config;
+  const { segments, loadModule, createElement, errorBoundaryComponent } = config;
 
   if (segments.length === 0) {
     throw new Error('[timber] buildElementTree: empty segment chain');
@@ -173,8 +176,8 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     );
   }
 
-  // Build the page element with params prop
-  let element: ReactElement = createElement(PageComponent, { params });
+  // Build the page element — params are accessed via rawSegmentParams() from ALS
+  let element: ReactElement = createElement(PageComponent, {});
 
   // Build tree bottom-up: wrap page, then walk segments from leaf to root
   for (let i = segments.length - 1; i >= 0; i--) {
@@ -195,7 +198,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
       const accessFn = accessModule.default as AccessGateProps['accessFn'];
       element = createElement('timber:access-gate', {
         accessFn,
-        params,
         segmentName: segment.segmentName,
         children: element,
       } satisfies AccessGateProps);
@@ -215,7 +217,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
           for (const [slotName, slotNode] of segment.slots) {
             slotProps[slotName] = await buildSlotElement(
               slotNode,
-              params,
               loadModule,
               createElement,
               errorBoundaryComponent
@@ -225,7 +226,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
 
         element = createElement(LayoutComponent, {
           ...slotProps,
-          params,
           children: element,
         });
       }
@@ -245,7 +245,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
  */
 async function buildSlotElement(
   slotNode: SegmentNode,
-  params: Record<string, string | string[]>,
   loadModule: ModuleLoader,
   createElement: CreateElement,
   errorBoundaryComponent: unknown
@@ -262,10 +261,10 @@ async function buildSlotElement(
 
   // If no page, render default.tsx or null
   if (!PageComponent) {
-    return DefaultComponent ? createElement(DefaultComponent, { params }) : null;
+    return DefaultComponent ? createElement(DefaultComponent, {}) : null;
   }
 
-  let element: ReactElement = createElement(PageComponent, { params });
+  let element: ReactElement = createElement(PageComponent, {});
 
   // Wrap in error boundaries
   element = await wrapWithErrorBoundaries(
@@ -287,11 +286,10 @@ async function buildSlotElement(
     const DeniedComponent =
       (deniedModule?.default as ((...args: unknown[]) => ReactElement) | undefined) ?? null;
 
-    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, { params }) : null;
+    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
 
     element = createElement('timber:slot-access-gate', {
       accessFn,
-      params,
       DeniedComponent,
       slotName: slotNode.segmentName.replace(/^@/, ''),
       createElement,

package/src/shared/merge-search-params.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared utility for merging preserved search params into a target URL.
+ *
+ * Used by both <Link> (client) and redirect() (server). Extracted to a shared
+ * module to avoid importing client code ('use client') from server modules.
+ */
+
+/**
+ * Merge preserved search params from the current URL into a target href.
+ *
+ * When `preserve` is `true`, all current search params are merged.
+ * When `preserve` is a `string[]`, only the named params are merged.
+ *
+ * The target href's own search params take precedence — preserved params
+ * are only added if the target doesn't already define them.
+ *
+ * @param targetHref - The resolved target href (may already contain query string)
+ * @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+ * @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+ * @returns The target href with preserved search params merged in
+ */
+export function mergePreservedSearchParams(
+  targetHref: string,
+  currentSearch: string,
+  preserve: true | string[]
+): string {
+  const currentParams = new URLSearchParams(currentSearch);
+  if (currentParams.size === 0) return targetHref;
+
+  // Split target into path and existing query
+  const qIdx = targetHref.indexOf('?');
+  const targetPath = qIdx >= 0 ? targetHref.slice(0, qIdx) : targetHref;
+  const targetParams = new URLSearchParams(qIdx >= 0 ? targetHref.slice(qIdx + 1) : '');
+
+  // Collect params to preserve (that aren't already in the target)
+  const merged = new URLSearchParams(targetParams);
+  for (const [key, value] of currentParams) {
+    // Only preserve if: (a) not already in target, and (b) included in preserve list
+    if (!targetParams.has(key)) {
+      if (preserve === true || preserve.includes(key)) {
+        merged.append(key, value);
+      }
+    }
+  }
+
+  const qs = merged.toString();
+  return qs ? `${targetPath}?${qs}` : targetPath;
+}