@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

package/src/server/pipeline-interception.ts

@@ -10,47 +10,96 @@
  */
 
 import { classifyUrlSegment } from '../routing/segment-classify.js';
-
-/** Result of a successful interception match. */
-export interface InterceptionMatchResult {
-  /** The pathname to re-match (the source/intercepting route's parent). */
-  sourcePathname: string;
-}
-
-/**
- * Check if a pathname starts with a prefix on a segment boundary.
- *
- * Prevents /feed from matching /feed-private — the prefix must be
- * followed by '/' or be an exact match.
- */
-function hasSegmentPrefix(pathname: string, prefix: string): boolean {
-  if (prefix === '/') return true;
-  if (!pathname.startsWith(prefix)) return false;
-  return pathname.length === prefix.length || pathname[prefix.length] === '/';
-}
+import type { InterceptionRewrite } from '../routing/interception.js';
 
 /**
  * Check if an intercepting route applies for this soft navigation.
  *
- * Matches the target pathname against interception rewrites, constrained
- * by the source URL (X-Timber-URL header — where the user navigates FROM).
+ * Two conditions must hold:
+ *
+ * 1. The **target** pathname matches the rewrite's intercepted pattern.
+ * 2. The **source** route — the page the user is navigating FROM, per the
+ *    validated X-Timber-URL header — renders the segment that owns the slot
+ *    holding the intercepting page (`interceptingScope`). Only then does that
+ *    slot exist in the rendered tree, so only then can the intercepting page
+ *    render.
  *
- * Returns the source pathname to re-match if interception applies, or null.
+ * Condition 2 replaced a URL-prefix check (TIM-1279). A prefix cannot
+ * distinguish a route-group-scoped interception from a genuinely root-level
+ * one — route groups are invisible in `urlPath`, so both collapse to "/" and
+ * the guard degenerates to always-true. Tree paths carry group identity.
+ * The scope check also subsumes the old segment-boundary rule: a source route
+ * under /feed-private has no "/feed" in its chain.
+ *
+ * A third condition lives with the caller, which owns route matching, and it
+ * applies to the `'slot'` shape only: the route produced by re-matching
+ * `interceptingPrefix` must pass through the scope too. Conditions 1–2 are
+ * about the route the user is leaving; the slot has to exist in the tree that
+ * actually renders. The `'children'` shape resolves its owner from the scope
+ * directly rather than from a pathname, so it satisfies that by construction.
+ *
+ * `resolveSourceScopes` is a thunk so its inputs are only resolved when some
+ * rewrite's pattern actually matches the target — the common case is no match
+ * at all. It returns the two client-supplied answers to "what is on screen?"
+ * as **separate sets, most authoritative first**: the tree paths the client
+ * says it has mounted, then those of the route the departing URL matches. It
+ * returns null only when neither yields anything, which is not a soft
+ * navigation this can reason about.
+ *
+ * They are two sets rather than one union because ranking needs a chain
+ * (TIM-1318). Each channel describes a single rendered chain, so within one the
+ * scopes are strictly nested and the deepest is the innermost owner. Unioned
+ * they are not: once a modal is open the address bar holds the *intercepted*
+ * URL, so the second channel describes the canonical branch — possibly an
+ * exclusive route group the client never mounted — and a deeper scope from
+ * there would outrank the owner actually on screen. Trying the mounted channel
+ * to exhaustion first keeps the fallback the union was there to provide while
+ * ranking only within one chain.
+ *
+ * Returns the winning build-time rewrite, or null. Only build-time values ever
+ * reach the renderer: the client-supplied header selects a rewrite but never
+ * becomes a rendered route or pathname.
+ *
+ * The **first** matching rewrite wins, and the caller does not fall back to the
+ * next one when the winner fails to resolve. That is deliberate and pre-dates
+ * the two shapes: a rewrite that matched the target and the scope described the
+ * author's intent, and quietly rendering some other author's interception
+ * instead would be harder to explain than rendering the canonical route.
+ *
+ * "First" is meaningful because the list arrives **deepest scope first** —
+ * `collectInterceptionRewrites` sorts it at build time, so the deepest owner a
+ * single chain passes through wins and nothing here has to score (TIM-1318).
+ * Tree-walk order used to decide it, which meant renaming a route group flipped
+ * which modal opened. The precondition is a property of the manifest this reads
+ * rather than something it can re-derive, so it is asserted at its source:
+ * `tests/interception.test.ts` §"rewrite order is decided by scope depth".
  */
 export function findInterceptionMatch(
   targetPathname: string,
-  sourceUrl: string,
-  rewrites: import('../routing/interception.js').InterceptionRewrite[]
-): InterceptionMatchResult | null {
-  for (const rewrite of rewrites) {
-    // Check if the source URL starts with the intercepting prefix,
-    // enforcing segment boundary to prevent /feed matching /feed-private.
-    if (!hasSegmentPrefix(sourceUrl, rewrite.interceptingPrefix)) continue;
+  resolveSourceScopes: () => ReadonlySet<string>[] | null,
+  rewrites: InterceptionRewrite[]
+): InterceptionRewrite | null {
+  // Dynamic segments in the pattern match any single URL segment. Collected up
+  // front rather than inside the channel loop so a pattern is matched once
+  // however many channels are tried — and the common case, no rewrite matching
+  // at all, costs exactly the same scan it always did and resolves no scope.
+  const candidates = rewrites.filter((rewrite) =>
+    pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)
+  );
+  if (candidates.length === 0) return null;
+
+  // Nothing at all is known about the source tree — no scope can contain
+  // anything, so no rewrite can apply.
+  const scopes = resolveSourceScopes();
+  if (!scopes) return null;
 
-    // Check if the target URL matches the intercepted pattern.
-    // Dynamic segments in the pattern match any single URL segment.
-    if (pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)) {
-      return { sourcePathname: rewrite.interceptingPrefix };
+  // `candidates` is deepest scope first (`collectInterceptionRewrites`), so
+  // within one channel the first hit is the innermost owner that channel
+  // reports. Channels are tried in order, so a scope the client says it has
+  // mounted always beats one only the address bar implies.
+  for (const scope of scopes) {
+    for (const rewrite of candidates) {
+      if (scope.has(rewrite.interceptingScope)) return rewrite;
     }
   }
   return null;

package/src/server/pipeline-outcome.ts

@@ -26,16 +26,14 @@ import {
 import { markResponseFlushed } from './request-context.js';
 import { RedirectSignal, DenySignal } from './primitives.js';
 import { isDebug } from './debug.js';
+import { rscErrorEnvelope } from '../shared/rsc-error-envelope.js';
 import type { PipelineConfig, RouteMatch } from './pipeline.js';
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 function rscErrorResponse(isRsc: boolean, status: number, headers?: Headers): Response {
   if (!isRsc) return new Response(null, { status });
-  const h = headers ?? new Headers();
-  h.set('X-Timber-Error', '1');
-  h.set('content-type', 'application/json; charset=utf-8');
-  return new Response(JSON.stringify({ error: true, status }), { status, headers: h });
+  return rscErrorEnvelope(status, headers);
 }
 
 // ─── Phase Outcome ─────────────────────────────────────────────────────────
@@ -132,7 +130,7 @@ export async function outcomeToResponse(
           `[timber] DenySignal(${outcome.signal.status}) from ${outcome.phase} phase — ` +
             `no renderDenyFallback configured, returning bare ${outcome.signal.status} response\n` +
             `  Request: ${ctx.method} ${ctx.path}\n` +
-            `  Add a not-found.tsx or error.tsx to render a custom deny page.`
+            `  Add a status-code file (e.g. 404.tsx) or error.tsx to render a custom deny page.`
         );
       }
       return new Response(null, { status: outcome.signal.status, headers });

package/src/server/pipeline-phases.ts

@@ -30,6 +30,8 @@ import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
 import { loadModule } from './safe-load.js';
 import { findInterceptionMatch } from './pipeline-interception.js';
+import { computeSegmentTreePaths } from '../routing/segment-keys.js';
+import { parseClientStateTree } from './state-tree-diff.js';
 import { applyCookieJar, cloneWithMutableHeaders, type ProxyResolver } from './pipeline-helpers.js';
 import { coerceSegmentParams } from './param-coercion.js';
 import { outcomeToResponse, type PhaseOutcome } from './pipeline-outcome.js';
@@ -293,17 +295,6 @@ export async function handleRequest(
         // outer Server-Timing writer can append without hitting an
         // immutable header bag (e.g. user returns Response.redirect()).
         if (handlerResult instanceof Response) {
-          if (method === 'HEAD') {
-            const headHeaders = new Headers(handlerResult.headers);
-            if (handlerResult.ok && !headHeaders.has('Cache-Control')) {
-              headHeaders.set('Cache-Control', 'public, max-age=14400, must-revalidate');
-            }
-            return new Response(null, {
-              status: handlerResult.status,
-              statusText: handlerResult.statusText,
-              headers: headHeaders,
-            });
-          }
           const res = cloneWithMutableHeaders(handlerResult);
           if (res.ok && !res.headers.has('Cache-Control')) {
             res.headers.set('Cache-Control', 'public, max-age=14400, must-revalidate');
@@ -401,14 +392,75 @@ export async function handleRequest(
       ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash)
       : null;
     if (validatedSourceUrl) {
-      const intercepted = findInterceptionMatch(
+      // The scope of an interception is the segment that owns the intercepting
+      // slot, so the guard asks whether the route the user is LEAVING renders
+      // that segment. Two independent answers to "what is on screen?", tried in
+      // order — deferred behind a thunk so neither runs unless a rewrite's
+      // target pattern matches.
+      //
+      // 1. What the client says it has mounted (X-Timber-State-Tree
+      //    `treePaths`). Authoritative about tree shape and nothing else.
+      // 2. What re-matching X-Timber-URL implies. Correct while the address bar
+      //    still holds the source page, which stops being true the moment a
+      //    modal is open — the address is then the *intercepted* URL and
+      //    re-matching it resolves through whichever group owns the canonical
+      //    page (TIM-1282).
+      //
+      // Neither is trusted: both are client-supplied, and satisfying the scope
+      // only selects which build-time rewrite applies. The rendered pathname is
+      // always the rewrite's own `interceptingPrefix`, the server re-derives the
+      // rendered chain from it below, and every access.ts runs regardless.
+      //
+      // They are handed over as two sets in that order rather than one union:
+      // each describes a single rendered chain, and only within one chain does
+      // "the deepest scope" name the innermost owner (TIM-1318). Unioned, a
+      // deeper scope from the address-implied canonical branch — which after
+      // (2) may be a route group the client never mounted — would outrank the
+      // owner actually on screen.
+      const resolveSourceScopes = () => {
+        const mounted = new Set(parseClientStateTree(req)?.treePaths ?? []);
+        const sourceRoute = config.matchRoute(validatedSourceUrl);
+        const addressed = new Set(sourceRoute ? computeSegmentTreePaths(sourceRoute.segments) : []);
+        const scopes = [mounted, addressed].filter((scope) => scope.size > 0);
+        // Neither channel produced a tree — no scope can contain anything, and
+        // an origin that matches no route is not a legitimate soft navigation.
+        return scopes.length > 0 ? scopes : null;
+      };
+      const rewrite = findInterceptionMatch(
         canonicalPathname,
-        validatedSourceUrl,
+        resolveSourceScopes,
         config.interceptionRewrites
       );
-      if (intercepted) {
-        const sourceMatch = config.matchRoute(intercepted.sourcePathname);
-        if (sourceMatch) {
+      if (rewrite?.mode === 'children') {
+        // Sibling layout swap (TIM-1280). Nothing is re-matched: the resolver
+        // addresses the owner directory by tree path and returns the chain
+        // `[…owner ancestors, interceptingNode, …descendants]`, which renders
+        // as an ordinary route. `interception` stays unset — there is no slot
+        // to intercept into, and setting it would additionally arm the modal
+        // path for every slot in the tree we are about to render.
+        //
+        // A null here means the scope named nothing in this manifest, or no
+        // intercepting child matched the target. Both fall through to the
+        // canonical route, which is what a hard navigation renders.
+        const interceptedMatch = config.matchInterceptedRoute?.(
+          canonicalPathname,
+          rewrite.interceptingScope
+        );
+        if (interceptedMatch) match = interceptedMatch;
+      } else if (rewrite) {
+        const sourceMatch = config.matchRoute(rewrite.interceptingPrefix);
+        // The scope test above was about the route the user is LEAVING. The
+        // route we are about to render is a different one —
+        // `interceptingPrefix` is URL-derived, and route groups are
+        // URL-invisible, so `/` can resolve into a sibling group that does not
+        // own the slot. Rendering that would reproduce the TIM-1278 failure on
+        // a valid tree: the rewrite hijacks the navigation and no slot exists
+        // to render the intercepting page. Fall through to the canonical
+        // target route instead.
+        const rendersTheSlot =
+          sourceMatch !== null &&
+          computeSegmentTreePaths(sourceMatch.segments).includes(rewrite.interceptingScope);
+        if (rendersTheSlot) {
           match = sourceMatch;
           interception = { targetPathname: canonicalPathname };
         }

package/src/server/pipeline.ts

@@ -35,6 +35,9 @@ import { makeProxyResolver } from './pipeline-helpers.js';
 import { handleRequest, runProxyPhase } from './pipeline-phases.js';
 import { outcomeToResponse } from './pipeline-outcome.js';
 import { canonicalize } from './canonicalize.js';
+import { enforceRscCacheKey, hardenRscPayloadResponse } from './rsc-cache-key-guard.js';
+import { stripHeadBody } from './head-response.js';
+import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.js';
 import { isDebug } from './debug.js';
 
 // ─── Route Match Result ────────────────────────────────────────────────────
@@ -142,6 +145,17 @@ export interface PipelineConfig {
    * See design/07-routing.md §"Intercepting Routes"
    */
   interceptionRewrites?: import('../routing/interception.js').InterceptionRewrite[];
+  /**
+   * Resolver for children-path interceptions — the sibling layout swap.
+   *
+   * Separate from `matchRoute` because it addresses the owner directory by
+   * tree path rather than by pathname, which needs the manifest tree itself.
+   * Omitting it disables the `'children'` interception shape and leaves the
+   * canonical route rendering, which is the fail-safe outcome.
+   *
+   * See design/07-routing.md §"Intercepting Routes"
+   */
+  matchInterceptedRoute?: import('./children-interception.js').InterceptedRouteMatcher;
   /**
    * Control Server-Timing header output.
    *
@@ -393,17 +407,30 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
               // DevSpanProcessor reads this for tree/summary output.
               await setSpanAttribute('http.response.status_code', result.status);
 
-              // Vary: Accept — CDNs must cache HTML and RSC payload responses
-              // separately for the same URL. Without this, a shared cache may
-              // serve an RSC Flight payload to a browser expecting HTML (or
-              // vice versa). See GHSA-wfc6-r584-vfw7, design/13-security.md.
+              // Vary on exactly the headers the `_rsc` cache key hashes.
               //
-              // Vary: X-Timber-URL — intercepting route responses depend on
-              // the source URL, so caches must store them separately.
-              const varyTokens = ['Accept'];
-              if (config.interceptionRewrites?.length) {
-                varyTokens.push('X-Timber-URL');
-              }
+              // Those two mechanisms answer the same question — which request
+              // headers change this response — so they are the same list, not
+              // two lists that happen to agree. A separate hand-written list
+              // here drifted from `RSC_KEY_HEADERS` the moment the key set
+              // grew, and the drift is invisible: `Vary` is the *fallback*
+              // layer, used only when a cache omits the query from its key,
+              // which is precisely when nobody is watching (TIM-1268).
+              //
+              // Why any of it: without `Vary: Accept` a shared cache may serve
+              // an RSC Flight payload to a browser expecting HTML, or the
+              // reverse (GHSA-wfc6-r584-vfw7, design/13-security.md). The
+              // `_rsc` param puts that distinction in the URL, so correctness
+              // no longer *depends* on `Vary` — which is opt-in configuration
+              // on Cloudflare and CloudFront. `Vary` covers the requests that
+              // arrive without the param: a stripped query, a hand-rolled
+              // client.
+              //
+              // It costs no hit rate. Document requests send no `X-Timber-*`
+              // header at all, so they collapse to a single cache key; payload
+              // requests are already fragmented by these same values via the
+              // URL.
+              const varyTokens = [...RSC_KEY_HEADERS];
               const existingVary = result.headers.get('Vary');
               const existingTokens = existingVary
                 ? existingVary
@@ -419,6 +446,26 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
                 );
               }
 
+              // A request may only claim an `_rsc` cache key that matches its
+              // own headers. The key is predictable by design, so without this
+              // a caller could render its own variant under another client's
+              // key and have a shared cache store it there (TIM-1268).
+              await enforceRscCacheKey(canonicalReq, result);
+
+              // Flight payloads must never be sniffable into a renderable
+              // type — applied at this single exit so every producer is
+              // covered, not just the success path (TIM-1268).
+              hardenRscPayloadResponse(result);
+
+              // A HEAD response carries the headers its GET would produce and
+              // no content (RFC 9110 §9.3.2). Applied at this single exit so
+              // every response shape is covered — page render, API route,
+              // metadata route, deny page, error page, proxy short-circuit —
+              // rather than per-renderer, where it was missing for page
+              // renders entirely (TIM-1324). The render still runs: the
+              // headers have to be the ones a GET would have sent.
+              result = stripHeadBody(result, method);
+
               // Append Server-Timing header based on configured mode.
               // Header mutability is guaranteed by the producer-side clone
               // in `outcomeToResponse` and the metadata-route / auto-sitemap

package/src/server/prebuilt-builder.ts

@@ -235,13 +235,7 @@ async function enumerateCombos(
 ): Promise<ParamCombo[] | null> {
   if (!hasDynamicSegments(route.urlPath)) return [{}];
 
-  let generateFn = pageModule.generateStaticSegmentParams;
-  if (typeof generateFn !== 'function' && typeof pageModule.generateStaticParams === 'function') {
-    generateFn = pageModule.generateStaticParams;
-    log(
-      `[timber] ${route.page.filePath}: generateStaticParams is deprecated — rename to generateStaticSegmentParams`
-    );
-  }
+  const generateFn = pageModule.generateStaticSegmentParams;
   if (typeof generateFn !== 'function') {
     log(
       `[timber] cache.component: route ${route.urlPath} has prebuilt components but no ` +

package/src/server/prebuilt-runtime.ts

@@ -173,17 +173,17 @@ const registry = new Map<string, PrebuiltRegistration>();
  */
 function resolveKeyParams(store: {
   segmentParams?: Record<string, string | string[]>;
-  slotParamsMap?: Map<string, Record<string, string | string[]>>;
+  slotParams?: Record<string, Record<string, string | string[]>>;
 }): Record<string, string | string[]> | null {
   const main = store.segmentParams ?? {};
-  const map = store.slotParamsMap;
-  if (!map || map.size === 0) return main;
+  const slots = store.slotParams;
+  if (!slots || Object.keys(slots).length === 0) return main;
   // Spread before canonicalizing: param records are framework-produced
   // Object.create(null) objects (prototype-pollution defense) — normalize
   // the records themselves, let nested values face the full allowlist.
   const mainCanonical = tryCanonicalize({ ...main });
   if (mainCanonical === null) return null;
-  for (const slotParams of map.values()) {
+  for (const slotParams of Object.values(slots)) {
     const merged = tryCanonicalize({ ...main, ...slotParams });
     if (merged === null || merged !== mainCanonical) return null;
   }

package/src/server/primitives.ts

@@ -201,15 +201,6 @@ export function deny(statusOrOptions?: number | DenyOptions, data?: JsonSerializ
   throw new DenySignal(status, resolvedData);
 }
 
-/**
- * @deprecated Use `deny(404)` instead.
- * Kept for internal use by the Next.js shim layer.
- * @internal
- */
-export function notFound(): never {
-  deny(404);
-}
-
 // Single source of truth shared with the client next/navigation shim —
 // see shared/redirect-type.ts.
 export { RedirectType } from '../shared/redirect-type.js';
@@ -334,15 +325,6 @@ export function redirect(path: string, statusOrOptions?: number | RedirectOption
   throw new RedirectSignal(resolvedPath, status);
 }
 
-/**
- * @deprecated Use `redirect(path, { permanent: true })` instead.
- * Kept for internal use by the Next.js shim layer.
- * @internal
- */
-export function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never {
-  redirect(path, { permanent: true, ...options });
-}
-
 /**
  * Redirect to an external URL. The origin must be in the provided allow-list.
  *

package/src/server/publish-params.ts

@@ -0,0 +1,42 @@
+/**
+ * Publishing the request's params onto the RSC payload.
+ *
+ * Every tree the server sends the browser goes through here: the ordinary
+ * route payload (`route-element-builder.ts`), both deny renderers
+ * (`deny-renderer.ts`) and the error renderer. One helper rather than a wrap
+ * at each site, because these previously *were* separate sites — a response
+ * header, an inline script, and a second copy of each on the deny path — and
+ * the deny path shipping empty params was the bug that came of it (TIM-1285).
+ *
+ * Reads the request store rather than taking params as an argument, so a
+ * caller cannot pass a different record than the one the request rendered
+ * with. See design/41-global-params.md §"Transport".
+ */
+
+import { toPlainRecord } from '../shared/param-value.js';
+import type { RscPayloadRoot } from '../shared/payload-root.js';
+import { getSegmentParamsForClient, getSlotParamsForClient } from './request-context.js';
+
+/**
+ * Build the payload root: the tree, and the params it rendered with beside it.
+ *
+ * The params are a *sibling* of the tree, not a provider around it. A provider
+ * inside the payload is shadowed by the retained tree's own provider on a
+ * partial navigation, and its props are not readable at the instant the root
+ * row resolves — see `shared/payload-root.ts` for both, and TIM-1297. The
+ * client renders the one provider readers see, above the merge point.
+ *
+ * The records are flattened to plain objects on the way out. Every param
+ * record the framework builds is `Object.create(null)` (design/13-security.md
+ * #36b/#36c), and React Flight rejects a null prototype — "Classes or null
+ * prototypes are not supported". `ParamsProvider` restores the prototype on
+ * the other side, so what the app reads is unchanged; only the wire
+ * representation differs.
+ */
+export function withPublishedParams(element: React.ReactElement): RscPayloadRoot {
+  return {
+    tree: element,
+    params: toPlainRecord(getSegmentParamsForClient()),
+    slotParams: toPlainRecord(getSlotParamsForClient() ?? null),
+  };
+}

package/src/server/request-context.ts

@@ -15,9 +15,14 @@
  */
 
 import { requestContextAls, type RequestContextStore } from './als-registry.js';
-import { _setGetSearchParamsFn } from '../search-params/define.js';
-import { _setGetSegmentParamsFn } from '../segment-params/define.js';
+import { _setGetSearchParamsFn, _setGetSegmentParamsFn } from '../shared/als-slots.js';
 import { consumeSeededCookies } from './cookie-context.js';
+import { appVisibleSearch } from '../shared/rsc-cache-key.js';
+import {
+  mergeSlotParams,
+  resolveSegmentParams,
+  type SlotParamsRecord,
+} from '../shared/slot-params.js';
 import { isDebug } from './debug.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
@@ -111,17 +116,13 @@ export function getSegmentParams(segmentPath?: string): Record<string, string |
     );
   }
 
-  // Check slot params map first — parallel slots may have different param
-  // types than the main route (e.g. catch-all [..year] → string[] vs
-  // dynamic [year] → string). If the requested segment path matches a
-  // stored slot, return its params merged with the main route's.
-  if (segmentPath && store.slotParamsMap?.has(segmentPath)) {
-    const slotParams = store.slotParamsMap.get(segmentPath)!;
-    // Merge: main params as base, slot-specific params override.
-    // This ensures params from segments above the slot (that the slot
-    // doesn't re-derive) are still available.
-    return { ...store.segmentParams, ...slotParams };
-  }
+  // Parallel slots may derive a param the main route never had, or the same
+  // name with a different type (catch-all [...year] → string[] vs dynamic
+  // [year] → string). `resolveSegmentParams` is the shared definition the
+  // client's useSegmentParams() also reads, so the two halves of one
+  // documented API cannot drift (TIM-1285).
+  const slotResolved = resolveSegmentParams(store.segmentParams, store.slotParams, segmentPath);
+  if (slotResolved !== store.segmentParams) return slotResolved;
 
   // Dev-mode validation: warn when the segment path expects dynamic
   // segments that don't exist on the actual matched segment. This catches
@@ -173,8 +174,82 @@ export function setSlotParams(
 ): void {
   const store = requestContextAls.getStore();
   if (!store) return; // non-throwing — optional diagnostic
-  if (!store.slotParamsMap) store.slotParamsMap = new Map();
-  store.slotParamsMap.set(segmentPath, params);
+  if (!store.slotParams) store.slotParams = Object.create(null) as SlotParamsRecord;
+  store.slotParams[segmentPath] = params;
+}
+
+/**
+ * Run `fn` with the segment params a parallel slot's own chain produced, so
+ * a no-arg `getSegmentParams()` inside that slot returns the slot's params
+ * rather than the main route's.
+ *
+ * ALS is the only channel available: the slot's page and layouts are plain
+ * components that receive no params prop and cannot know their own tree
+ * path, so they have no way to ask for the keyed overload. The slot resolver
+ * invokes each of them itself (page through `SafeSlotPage`, layouts and
+ * access functions through their wrappers), and this scopes those calls.
+ *
+ * The store is wrapped in a Proxy rather than cloned. Everything a slot
+ * renders can write to the *live* request store — `setDenyStatus` from an
+ * access gate, cookie writes, the flush flag — and a clone would silently
+ * strand those writes in a copy the pipeline never reads. Only the two
+ * params fields are shadowed; every other read and every write passes
+ * straight through to the real store.
+ *
+ * Returns `fn()`'s result unchanged, and no-ops outside a request context or
+ * before route matching has set the main params. See TIM-1283.
+ *
+ * @internal — framework use only
+ */
+export function runWithSlotSegmentParams<T>(
+  slotSegmentPath: string | undefined,
+  slotParams: Record<string, string | string[]>,
+  fn: () => T
+): T {
+  const store = requestContextAls.getStore();
+  if (!store?.segmentParams) return fn();
+
+  const merged = mergeSlotParams(store.segmentParams, slotParams);
+  const matchedSegmentPath = slotSegmentPath ?? store.matchedSegmentPath;
+  const scoped = new Proxy(store, {
+    get(target, prop, receiver) {
+      if (prop === 'segmentParams') return merged;
+      if (prop === 'matchedSegmentPath') return matchedSegmentPath;
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+  return requestContextAls.run(scoped, fn);
+}
+
+/**
+ * The main route's coerced params, or an empty record before route matching.
+ *
+ * Non-throwing, unlike `getSegmentParams()`: the deny payload path publishes
+ * params from wherever the pipeline happened to fail, which may be before
+ * matching completed.
+ *
+ * @internal — framework use only. See TIM-1285.
+ */
+export function getSegmentParamsForClient(): Record<string, string | string[]> {
+  return requestContextAls.getStore()?.segmentParams ?? {};
+}
+
+/**
+ * The per-slot params to publish to the client, or `undefined` when the
+ * request rendered no slot with params of its own.
+ *
+ * The client cannot derive these: a slot matches the URL through its own
+ * sub-tree, and the browser only ever sees the main route's record. Reading
+ * the map here — rather than threading it back out of the element builder —
+ * keeps one producer, since `setSlotParams` already writes it during slot
+ * resolution and every serialization site runs after that completes.
+ *
+ * @internal — framework use only. See TIM-1285.
+ */
+export function getSlotParamsForClient(): SlotParamsRecord | undefined {
+  const store = requestContextAls.getStore();
+  if (!store?.slotParams) return undefined;
+  return Object.keys(store.slotParams).length > 0 ? store.slotParams : undefined;
 }
 
 /**
@@ -247,7 +322,7 @@ export type ReadonlyHeaders = Pick<
  */
 export function runWithRequestContext<T>(req: Request, fn: () => T): T {
   const originalCopy = new Headers(req.headers);
-  const parsedUrl = new URL(req.url);
+  const appVisible = appVisibleSearch(new URL(req.url));
   const seed = consumeSeededCookies(req);
   const store: RequestContextStore = {
     headers: freezeHeaders(req.headers),
@@ -257,8 +332,12 @@ export function runWithRequestContext<T>(req: Request, fn: () => T): T {
     // gated on `parsedCookies` being undefined.
     cookieHeader: seed ? '' : (req.headers.get('cookie') ?? ''),
     parsedCookies: seed,
-    searchParams: parsedUrl.searchParams,
-    searchString: parsedUrl.search,
+    // Not `parsedUrl.searchParams` / `parsedUrl.search`: this store is what
+    // `getSearchParams()` and `redirect({ preserveSearchParams })` read, and
+    // the RSC payload URL carries the framework's `_rsc` cache key that no
+    // other request has (TIM-1272).
+    searchParams: appVisible.params,
+    searchString: appVisible.search,
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,