@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/search-params/define.ts

@@ -14,35 +14,13 @@ import { useQueryStates as clientUseQueryStates } from '../client/use-query-stat
 import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
 import type { Codec } from '../codec.js';
-
-// Server-only reference for .get() — avoids pulling server ALS into client bundles.
-// In client environments, .get() throws before reaching this code path.
-//
-// IMPORTANT: This is set eagerly via _setGetSearchParamsFn() at server startup
-// (called from request-context.ts module initialization). It must NOT use
-// dynamic `await import()` at call time because the async microtask from the
-// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,
-// breaking getSearchParams() in parallel slot pages. See TIM-523.
-let _getSearchParamsFn: (() => URLSearchParams) | undefined;
-
-/**
- * Register the getSearchParams function. Called once at module load time
- * from request-context.ts to avoid dynamic import at call time.
- * @internal
- */
-export function _setGetSearchParamsFn(fn: () => URLSearchParams): void {
-  _getSearchParamsFn = fn;
-}
-
-function getSearchParamsFromAls(): URLSearchParams {
-  if (!_getSearchParamsFn) {
-    throw new Error(
-      '[timber] searchParams.get() is only available on the server. ' +
-        'Use searchParams.useQueryStates() on the client.'
-    );
-  }
-  return _getSearchParamsFn();
-}
+// Server-only reference for .get() — avoids pulling server ALS into client
+// bundles. In client environments, .get() throws before reaching this code
+// path. The slot lives in its own leaf module so that `request-context.ts`
+// can register the getter without importing this file, which would drag
+// `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.
+import { getSearchParamsFromAls } from '../shared/als-slots.js';
+import { parseTotal } from './parse-total.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -51,13 +29,43 @@ function getSearchParamsFromAls(): URLSearchParams {
 /**
  * A codec that converts between URL string values and typed values.
  *
- * nuqs parsers implement this interface natively — no adapter needed.
+ * `parse` receives the RAW url value: `string | string[] | undefined`.
+ * A codec must be TOTAL over that domain — return a default rather than
+ * throwing on an absent or repeated param.
+ *
+ * A codec whose own `parse` covers only a PRESENT, SINGLE-VALUED param
+ * may publish `parseServerSide` instead, and timber calls that. nuqs
+ * parsers do exactly this, which is how they become total here: absent →
+ * `null` (or their `withDefault` value), repeated → the first value, and
+ * a throw from the inner parse → `null`. See
+ * design/23-search-params.md §'nuqs parsers, made total',
+ * `parse-total.ts`, and tests/nuqs-codec-boundary.test.ts (TIM-1350).
+ *
  * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected
- * by defineSearchParams and wrapped via fromSchema.
+ * by defineSearchParams and wrapped via fromSchema; those ARE total
+ * through `parse` and are called that way.
  */
 export interface SearchParamCodec<T> extends Codec<T> {
   /** Optional URL key alias, set by withUrlKey(). */
   urlKey?: string;
+  /**
+   * Optional TOTAL entry point over `string | string[] | undefined`,
+   * preferred over `parse` wherever timber invokes a codec. Declared here
+   * so the protocol is typed rather than duck-checked at each wrapper:
+   * anything that reconstructs a codec has to carry it, and a wrapper
+   * cannot carry a property the interface does not admit.
+   *
+   * It returns `T`, not `T | null`. This is the entry point timber calls,
+   * so whatever it returns IS the field's type — admitting a `null` the
+   * field type did not carry would let `SearchParamCodec<string>` produce
+   * `null` for an absent param under a non-nullable annotation. A codec
+   * whose absent-case answer is `null` declares that in `T`, exactly as a
+   * bare nuqs parser does: `parseAsString` is a `SearchParamCodec<string |
+   * null>` here, never a `SearchParamCodec<string>`.
+   *
+   * nuqs parser builders satisfy this. See parse-total.ts.
+   */
+  parseServerSide?(value: string | string[] | undefined): T;
 }
 
 /** A codec with a URL key alias attached via withUrlKey(). */
@@ -116,7 +124,7 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
    *
    * ```tsx
    * // app/products/page.tsx
-   * import { searchParams } from './params'
+   * import { searchParams } from './search-params'
    * export default function Page() {
    *   const { page, category } = searchParams.get()
    * }
@@ -135,15 +143,21 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
   /** Pick a subset of keys. Preserves codecs and aliases. */
   pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;
 
-  /** Serialize values to a query string (no leading '?'), omitting defaults. */
-  serialize(values: Partial<T>): string;
+  /**
+   * Serialize values to a query string (no leading '?'), omitting defaults
+   * and applying `withUrlKey` aliases. This is the value to pass to
+   * `<Link searchParams={...}>`.
+   *
+   * Returns a **string**, not a `URLSearchParams`. A `<Link>` prop crosses
+   * the RSC Flight boundary, and `URLSearchParams` is iterable — React
+   * serializes it as an entries array, which arrives as `[['pg','2'], …]`
+   * and renders as `?0=pg&0=2`. A string survives intact.
+   */
+  buildSearchParams(values: Partial<T>): string;
 
   /** Build a full path with query string, omitting defaults. */
   href(pathname: string, values: Partial<T>): string;
 
-  /** Build a URLSearchParams instance, omitting defaults. */
-  toSearchParams(values: Partial<T>): URLSearchParams;
-
   /** Read-only codec map for spreading into .extend(). */
   codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
 
@@ -182,6 +196,21 @@ type InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }
 /**
  * Infer the output type from either a SearchParamCodec or a StandardSchemaV1.
  *
+ * A codec publishing `parseServerSide` is read through THAT signature, not
+ * through `parse` — it is the entry point timber actually calls, and it is
+ * the one that tells the truth about absent input. A bare `parseAsString`
+ * declares `parse(value: string): string` but answers `null` for a missing
+ * param, so the field is `string | null`; `parseAsInteger.withDefault(1)`
+ * narrows its own `parseServerSide` to `NonNullable<number>` and the field
+ * stays `number`. Reading `parse` instead produced a non-nullable type for
+ * a nullable field (TIM-1350).
+ *
+ * The match is structural, not nuqs-specific: any codec declaring that
+ * signature opts into being read through it, which is exactly the contract
+ * `parseTotal` applies at runtime. The two must stay in step — a type
+ * inferred from `parse` while the runtime calls `parseServerSide` is the
+ * lie this branch exists to remove.
+ *
  * Schemas whose input type rejects `undefined` (e.g. bare `z.string()`, whose
  * input is `string`) are implicitly optional: the URL might not contain the
  * param, and fromSchema returns `undefined` when the schema rejects absent
@@ -194,8 +223,11 @@ type InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }
  * keeps its narrow output type even though absent input yields `undefined`
  * at runtime. Add `.default()` to coerce schemas for accurate types.
  */
-export type InferField<V> =
-  V extends SearchParamCodec<infer T>
+export type InferField<V> = V extends {
+  parseServerSide(value: string | string[] | undefined): infer R;
+}
+  ? R
+  : V extends SearchParamCodec<infer T>
     ? T
     : V extends StandardSchemaV1<infer T>
       ? undefined extends InferSchemaInput<V>
@@ -233,13 +265,36 @@ function normalizeRaw(
  * default-omission: when serialize(value) === serialize(parse(undefined)),
  * the field is omitted from the URL.
  *
+ * Goes through `parseTotal` for the same reason request-time parsing does:
+ * a nuqs parser's own `parse` throws on absent input, and this is the
+ * absent case by construction.
+ *
+ * **A codec with no value for an absent param has no default to omit**,
+ * and `null` is returned rather than `serialize(null)`. Serializing it
+ * makes the "no value" case collide with a real one: `parseAsInteger`
+ * serializes `null` as the string `'null'`, so `buildSearchParams({ q:
+ * 'null' })` would silently drop a legitimate value (before TIM-1350 the
+ * absent parse was `undefined` and the swallowed input was the string
+ * `'undefined'` — same defect, a less likely input). Nothing is lost:
+ * `buildSearchParams` already skips a field whose `serialize` returns
+ * `null`, so a codec that encodes "no value" as an omission behaves
+ * identically, and one that encodes it as a real query value now writes
+ * it instead of dropping it.
+ *
  * Codecs are documented to return a default rather than throw, but a
  * hand-written codec that throws on absent input must not turn definition
- * into a crash — treat its default as null (nothing to omit).
+ * into a crash — treat its default as null (nothing to omit). `serialize`
+ * is inside the try for the same reason.
+ *
+ * Typed `SearchParamCodec<unknown>` rather than generic on purpose: the
+ * absent-input value is whatever the codec's total entry point returns,
+ * which for a nuqs parser is `T | null` while its `serialize` declares
+ * `T`. Widening to `unknown` states that honestly instead of casting.
  */
-function getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {
+function getDefaultSerialized(codec: SearchParamCodec<unknown>): string | null {
   try {
-    return codec.serialize(codec.parse(undefined));
+    const absent = parseTotal(codec, undefined);
+    return absent === null || absent === undefined ? null : codec.serialize(absent);
   } catch {
     return null;
   }
@@ -405,7 +460,7 @@ function buildDefinition<T extends Record<string, unknown>>(
     for (const prop of Object.keys(codecMap)) {
       const urlKey = getUrlKey(prop);
       const rawValue = normalized[urlKey];
-      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);
+      result[prop] = parseTotal(codecMap[prop as keyof T] as SearchParamCodec<unknown>, rawValue);
     }
 
     return result as T;
@@ -429,8 +484,14 @@ function buildDefinition<T extends Record<string, unknown>>(
     return parseSync(raw);
   }
 
-  // ---- serialize ----
-  function serialize(values: Partial<T>): string {
+  // ---- buildSearchParams ----
+  //
+  // Returns a query string. It used to have a URLSearchParams-returning
+  // sibling (`toSearchParams`) that `<Link>` consumed; that shape cannot
+  // cross the RSC Flight boundary (see the interface docstring), and having
+  // two methods produce the same query two ways was a drift waiting to
+  // happen. One method now.
+  function buildSearchParams(values: Partial<T>): string {
     const parts: string[] = [];
 
     for (const prop of Object.keys(codecMap)) {
@@ -450,28 +511,10 @@ function buildDefinition<T extends Record<string, unknown>>(
 
   // ---- href ----
   function href(pathname: string, values: Partial<T>): string {
-    const qs = serialize(values);
+    const qs = buildSearchParams(values);
     return qs ? `${pathname}?${qs}` : pathname;
   }
 
-  // ---- toSearchParams ----
-  function toSearchParams(values: Partial<T>): URLSearchParams {
-    const usp = new URLSearchParams();
-
-    for (const prop of Object.keys(codecMap)) {
-      if (!(prop in values)) continue;
-      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;
-      const serialized = codec.serialize(values[prop as keyof T] as unknown);
-
-      if (serialized === defaultSerialized[prop]) continue;
-      if (serialized === null) continue;
-
-      usp.set(getUrlKey(prop), serialized);
-    }
-
-    return usp;
-  }
-
   // ---- extend ----
   function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(
     newCodecs: U
@@ -565,9 +608,8 @@ function buildDefinition<T extends Record<string, unknown>>(
     useQueryStates,
     extend,
     pick,
-    serialize,
     href,
-    toSearchParams,
+    buildSearchParams,
     codecs: codecMap,
     urlKeys: Object.freeze({ ...urlKeys }),
   };

package/src/search-params/index.ts

@@ -25,4 +25,3 @@ export { defineSearchParams } from './define.js';
 export { withDefault, withUrlKey } from './wrappers.js';
 
 // Runtime registry (route-scoped useQueryStates)
-export { registerSearchParams, getSearchParamsDefinition } from './registry.js';

package/src/search-params/parse-total.ts

@@ -0,0 +1,78 @@
+/**
+ * parseTotal — invoke a codec over the FULL raw domain.
+ *
+ * `SearchParamCodec.parse` is documented to be total over
+ * `string | string[] | undefined`, because that is exactly what a URL
+ * hands it: a param can be absent (`undefined`) or repeated (`string[]`).
+ * Timber's own codecs and the Standard Schema bridges honour that.
+ *
+ * nuqs parsers do not. Their `parse` expects a **present scalar string** —
+ * nuqs checks presence itself before ever calling it — so `parseAsBoolean`
+ * and `parseAsIsoDate` threw a render-phase 500 on an absent param and
+ * `parseAsString` returned an array on a repeated one (TIM-1350).
+ *
+ * nuqs ships the missing adapter: every parser builder exposes
+ * `parseServerSide(value: string | string[] | undefined)`, which maps
+ * absent → `null` (or the parser's `withDefault` value), takes the FIRST
+ * entry of a repeated param (matching `URLSearchParams.get()`), and wraps
+ * the inner `parse` so a throw becomes `null`. That is precisely timber's
+ * domain, so we call it in preference to `parse` rather than hand-rolling
+ * a second normalization that could disagree with the client hook.
+ *
+ * Feature detection, not an instanceof check: any codec MAY publish
+ * `parseServerSide` to declare "this is my total entry point" — it is an
+ * optional member of `SearchParamCodec` — and a codec that does not is
+ * assumed already total and called through `parse`. Timber codecs and
+ * schema bridges take the second branch untouched; several of them rely on
+ * `parse(undefined)` to produce their default.
+ *
+ * **Search params only.** Segment params (`server/param-coercion.ts`) call
+ * `codec.parse` directly and must keep doing so: their domain is a value
+ * the router matched, never absent, and a codec that REJECTS one is how a
+ * route produces a 404. Routing a rejection through nuqs's `safeParse`
+ * would turn that 404 into a silent `null` param. The two domains differ
+ * in what "no value" means, not just in plumbing. Cookies are a third
+ * domain (`cookies/define-cookie.ts`) and are likewise untouched.
+ *
+ * `parseServerSide` carries a `@deprecated` tag in nuqs (it steers users to
+ * loaders, which timber does not use). It remains public, typed and
+ * exercised; `tests/nuqs-codec-boundary.test.ts` asserts totality for every
+ * parser through timber's own API, so a nuqs release that drops it fails
+ * loudly rather than silently reinstating the 500s.
+ *
+ * Design doc: design/23-search-params.md §"nuqs parsers, made total"
+ */
+
+import type { Codec } from '../codec.js';
+
+/**
+ * A codec that publishes a total entry point over the raw URL domain.
+ *
+ * The return is `T`, not `T | null`: this is the entry point timber calls,
+ * so whatever it answers IS the field's type. A `null` for an absent param
+ * belongs in `T` — a bare nuqs parser is a codec of `string | null`, and
+ * `parseAsInteger.withDefault(1)` is a codec of `number`, because nuqs
+ * narrows its own `parseServerSide` return to `NonNullable<T>`. Declaring
+ * `T | null` here would let a codec annotated `SearchParamCodec<string>`
+ * hand back `null` under a non-nullable type (TIM-1350 review).
+ */
+export interface TotalCodec<T> {
+  parseServerSide(value: string | string[] | undefined): T;
+}
+
+function hasParseServerSide<T>(codec: Codec<T>): codec is Codec<T> & TotalCodec<T> {
+  return typeof (codec as Partial<TotalCodec<T>>).parseServerSide === 'function';
+}
+
+/**
+ * Parse a raw URL value through a codec, using the codec's total entry
+ * point when it publishes one.
+ *
+ * Returns `T`, from both branches. A `null` for an absent param is part of
+ * the codec's own `T` — see TotalCodec above — so this signature does not
+ * widen it, and a caller that must handle "no value" (`withDefault`) sees
+ * it because `T` carries it.
+ */
+export function parseTotal<T>(codec: Codec<T>, raw: string | string[] | undefined): T {
+  return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);
+}

package/src/search-params/wrappers.ts

@@ -15,14 +15,32 @@ import type {
   SearchParamField,
 } from './define.js';
 import { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';
+import { parseTotal } from './parse-total.js';
 
 // ---------------------------------------------------------------------------
 // withDefault
 // ---------------------------------------------------------------------------
 
 /**
- * Wrap a nullable codec with a default value. When the inner codec returns
- * null, the default is used instead. The output type becomes non-nullable.
+ * Wrap a nullable codec with a default value. The output type becomes
+ * non-nullable, and the wrapper is TOTAL over `string | string[] |
+ * undefined` even when the inner codec is not.
+ *
+ * The default is substituted for `null` — the documented "no value"
+ * answer — and for `undefined`, which is what an implicitly-optional
+ * Standard Schema field and a bare `parseAsString` produce for an absent
+ * param. Substituting only for `null` left a field typed non-nullable
+ * `string` holding `undefined` (TIM-1350).
+ *
+ * The inner codec is invoked through `parseTotal`, so a nuqs parser gets
+ * its own normalization (absent → null, repeated → first value, inner
+ * throw → null) before either check applies. That is what makes
+ * `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT
+ * catch. A throw from a codec is a deliberate signal — `fromSchema` throws
+ * on an async schema, and an app codec may `redirect()` or `notFound()` on
+ * a value it refuses — and swallowing it would convert a loud failure into
+ * a permanently-default field. design/09 §"The SearchParamCodec Protocol":
+ * a codec that throws bubbles as a render-phase error, by design.
  *
  * Works with any codec — nuqs parsers, custom codecs, fromSchema results.
  *
@@ -34,20 +52,35 @@ import { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';
  * // page.parse(undefined) → 1 (not null)
  * // page.parse('5') → 5
  * ```
+ *
+ * The signature strips BOTH nullish constituents from the result, not just
+ * `null`, because the runtime substitutes for both. An implicitly-optional
+ * schema field is a `SearchParamCodec<string | undefined>`, and wrapping it
+ * used to yield `SearchParamCodec<string | undefined>` — a field the
+ * wrapper guarantees is always present, still typed as maybe-absent.
  */
 export function withDefault<T>(
-  codec: SearchParamCodec<T | null>,
-  defaultValue: T
-): SearchParamCodec<T> {
-  return {
-    parse(value: string | string[] | undefined): T {
-      const result = codec.parse(value);
-      return result === null ? defaultValue : result;
+  codec: SearchParamCodec<T | null | undefined>,
+  defaultValue: NonNullable<T>
+): SearchParamCodec<NonNullable<T>> {
+  // A wrapper that rebuilds a codec from two methods drops everything else
+  // the codec carries. `withUrlKey` lost `parseServerSide` that way; this
+  // one lost `urlKey`, so `withDefault(withUrlKey(parseAsInteger, 'p'), 1)`
+  // silently read `?page=` instead of `?p=`. Carry it explicitly rather
+  // than spreading: this wrapper's own `parse` IS the total entry point,
+  // and re-publishing the inner `parseServerSide` would let `parseTotal`
+  // reach past it and skip the default entirely.
+  const wrapped: SearchParamCodec<NonNullable<T>> = {
+    parse(value: string | string[] | undefined): NonNullable<T> {
+      const result = parseTotal(codec, value);
+      return result === null || result === undefined ? defaultValue : result;
     },
-    serialize(value: T): string | null {
+    serialize(value: NonNullable<T>): string | null {
       return codec.serialize(value);
     },
   };
+  if (codec.urlKey !== undefined) wrapped.urlKey = codec.urlKey;
+  return wrapped;
 }
 
 // ---------------------------------------------------------------------------
@@ -93,9 +126,25 @@ export function withUrlKey<F extends SearchParamField>(
     : isStandardSchema(codecOrSchema)
       ? (fromSchema(codecOrSchema) as SearchParamCodec<T>)
       : (codecOrSchema as SearchParamCodec<T>);
-  return {
+  // Carry the total entry point, bound like the other two methods. A
+  // codec's totality lives in a THIRD property, `parseServerSide` (see
+  // parse-total.ts); picking only `parse`/`serialize` silently produced a
+  // non-total alias, so `withUrlKey(parseAsBoolean, 'b')` threw on an
+  // absent param while the bare parser did not (TIM-1350).
+  //
+  // Bound explicitly rather than spread: a spread copies own enumerable
+  // properties only, so a class-based codec — whose `parse` and
+  // `serialize` this wrapper already reaches through the prototype —
+  // would have kept its methods and lost exactly the one that makes it
+  // total. Three properties, one rule, no dependence on how the inner
+  // codec was constructed.
+  const wrapped: SearchParamCodecWithUrlKey<T> = {
     parse: codec.parse.bind(codec),
     serialize: codec.serialize.bind(codec),
     urlKey,
   };
+  if (typeof codec.parseServerSide === 'function') {
+    wrapped.parseServerSide = codec.parseServerSide.bind(codec);
+  }
+  return wrapped;
 }

package/src/server/access-gate.tsx

@@ -18,7 +18,7 @@ import type { AccessGateProps, SlotAccessGateProps } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
 import { isDebug } from './debug.js';
 import type { DenyPageEntry } from './deny-boundary.js';
-import { renderMatchingDenyPage, setDenyStatus } from './deny-boundary.js';
+import { handleCaughtDeny, setFirstDeniedSegmentIndex } from './deny-boundary.js';
 import type { ReactNode } from 'react';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
@@ -26,50 +26,64 @@ import type { ReactNode } from 'react';
 /**
  * Framework-injected access gate for segments.
  *
- * When a pre-computed `verdict` prop is provided (from the pre-render pass
- * in route-element-builder.ts), AccessGate replays it synchronously — no
- * async, no re-execution of access.ts, immune to Suspense timing. The OTEL
- * span was already emitted during the pre-render pass.
- *
- * When no verdict is provided (backward compat with tree-builder.ts),
- * AccessGate calls accessFn directly with OTEL instrumentation.
+ * Calls accessFn during render — inside `renderToReadableStream`, sharing
+ * the same `React.cache` scope as layouts and pages. A `requireUser()`
+ * call in access.ts populates the cache; the same call in any layout is
+ * a free hit. Access executes exactly once per request. See TIM-1363.
  *
  * access.ts is a pure gate — return values are discarded. The layout below
  * gets the same data by calling the same cached functions (React.cache dedup).
+ *
+ * On denial the gate renders the matching deny page only when this segment
+ * owns it. Because the gate is wrapped OUTSIDE its own layout, that render
+ * omits the denying segment's layout — deliberate, and the one place the
+ * in-tree path diverges from `renderDenyPage`'s inclusive slice: a layout
+ * whose access.ts denied must never run and serialize protected data into
+ * the Flight stream (TIM-1074). An ancestor-owned page is hoisted instead,
+ * because the gate also sits inside every layout above it and rendering
+ * here would wrap the deny page in all of them (TIM-1356).
+ *
+ * For skipped segments (skippedSegment=true), deny pages are NOT rendered
+ * in-tree — the client's cached layout chrome would wrap them incorrectly.
+ * Instead, the deny is recorded in ALS and rethrown so the response path
+ * can return rscErrorEnvelope for a client hard-navigate.
  */
-export function AccessGate(props: AccessGateProps): ReactNode | Promise<ReactNode> {
-  const { accessFn, segmentName, verdict, denyPages, children } = props;
+export function AccessGate(props: AccessGateProps): Promise<ReactNode> {
+  const {
+    accessFn,
+    segmentName,
+    segmentKey,
+    segmentIndex,
+    denyPages,
+    skippedSegment,
+    onSettled,
+    children,
+  } = props;
 
-  // Fast path: replay pre-computed verdict from the pre-render pass.
-  if (verdict !== undefined) {
-    if (verdict === 'pass') {
-      return children;
-    }
-    // Render deny page in-tree when possible (same as the fallback path).
-    if (verdict instanceof DenySignal && denyPages) {
-      const denyElement = renderMatchingDenyPage(denyPages, verdict.status, verdict.data);
-      if (denyElement) {
-        setDenyStatus(verdict.status);
-        return denyElement;
-      }
-    }
-    throw verdict;
-  }
-
-  // Primary path: call accessFn directly during render.
-  // If denyPages is provided, catch DenySignal and render the deny page
-  // in-tree — no throw reaches React Flight, no second render pass.
-  return accessGateFallback(accessFn, segmentName, denyPages, children);
+  return accessGateFallback(
+    accessFn,
+    segmentName,
+    segmentKey,
+    segmentIndex,
+    skippedSegment ? undefined : denyPages,
+    skippedSegment,
+    onSettled,
+    children
+  );
 }
 
 /**
- * Async fallback for AccessGate when no pre-computed verdict is available.
- * Calls accessFn with OTEL instrumentation.
+ * Calls accessFn during render with OTEL instrumentation.
+ * Records the first denied segment index in ALS for post-render consumers.
  */
 async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
   segmentName: AccessGateProps['segmentName'],
+  segmentKey: AccessGateProps['segmentKey'],
+  segmentIndex: AccessGateProps['segmentIndex'],
   denyPages: DenyPageEntry[] | undefined,
+  skippedSegment: boolean | undefined,
+  onSettled: (() => void) | undefined,
   children: ReactNode
 ): Promise<ReactNode> {
   try {
@@ -91,17 +105,23 @@ async function accessGateFallback(
       }
     });
   } catch (error: unknown) {
-    // Catch DenySignal and render the deny page in-tree.
-    // No throw reaches React Flight — clean stream, single render pass.
-    // RedirectSignal and other errors propagate normally.
-    if (error instanceof DenySignal && denyPages) {
-      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
-      if (denyElement) {
-        setDenyStatus(error.status);
-        return denyElement;
+    if (error instanceof DenySignal) {
+      if (segmentIndex !== undefined) {
+        setFirstDeniedSegmentIndex(segmentIndex);
+      }
+
+      if (skippedSegment) {
+        error._hardNavigate = true;
+        throw error;
+      }
+
+      if (denyPages) {
+        return handleCaughtDeny(denyPages, error, segmentKey);
       }
     }
     throw error;
+  } finally {
+    onSettled?.();
   }
 
   return children;

package/src/server/action-handler.ts

@@ -36,6 +36,7 @@ import {
 import type { FormFlashData } from './form-flash.js';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { logActionError } from './logger.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -55,10 +56,6 @@ export interface ActionDispatchConfig {
   sensitiveFields?: SensitiveFieldsOption;
 }
 
-// ─── Constants ────────────────────────────────────────────────────────────
-
-const RSC_CONTENT_TYPE = 'text/x-component';
-
 // ─── Detection ────────────────────────────────────────────────────────────
 
 /**
@@ -296,7 +293,9 @@ async function handleRscAction(
     // serialized together so React Flight handles both in one stream.
     payload = {
       _action: result.actionResult,
-      _tree: result.revalidation.element,
+      // The payload root, not a bare tree: it carries the revalidated
+      // route's params too, and the client publishes them (TIM-1297).
+      _tree: result.revalidation.payload,
     };
     headers['X-Timber-Revalidation'] = '1';
     // Metadata (<title>/<meta>/<link>) now rides the revalidation element

package/src/server/actions.ts

@@ -20,10 +20,13 @@ import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
 // ─── Types ───────────────────────────────────────────────────────────────
 
-/** Result of rendering a revalidation — element tree before RSC serialization. */
+/** Result of rendering a revalidation — payload root before RSC serialization. */
 export interface RevalidationResult {
-  /** React element tree (pre-serialization — passed to renderToReadableStream). */
-  element: unknown;
+  /**
+   * The payload root — tree plus the params it rendered with, exactly as an
+   * ordinary route payload. The client splits it in `applyRevalidation`.
+   */
+  payload: unknown;
 }
 
 /** Renderer function that builds a React element tree for a given path. */