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

package/src/cli.ts

@@ -11,28 +11,49 @@
 //   timber preview  — Serve the production build
 //   timber check    — Validate types + routes without building
 
+// Type-only — the implementation is imported dynamically inside runCheck so the
+// CLI's other commands never load the route scanner.
+import type { CheckDeps } from './cli-check.js';
+
+export type { CheckDeps };
+
 const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
   command: Command;
   config: string | undefined;
+  /** `--project`: the tsconfig `timber check` passes to tsgo. */
+  project: string | undefined;
   /** Positional arguments after the command (used by `timber schema sync`). */
   rest: string[];
 }
 
 export interface CommandOptions {
+  /** Path to a Vite config file. Means the same thing for every command. */
   config?: string;
+  /** `timber check` only: the tsconfig to type-check. */
+  project?: string;
 }
 
 /**
  * Parse CLI arguments into a structured command + options.
- * Accepts: timber <command> [--config|-c <path>]
+ * Accepts: timber <command> [--config|-c <path>] [--project <path>]
+ *
+ * `--config` names a **Vite** config file for every command, `check` included
+ * (TIM-1332): `check` resolves the project through Vite, so a project that
+ * builds with `--config ./custom.vite.config.ts` has to be checkable the same
+ * way. `--project` names the tsconfig, spelled as tsgo and tsc spell it, and
+ * is meaningful only for `check`.
+ *
+ * Before TIM-1332 `--config` meant the tsconfig for `check` alone — one flag
+ * with two meanings, which the docs had to carry a note to explain and which
+ * left custom Vite configs unreachable from `check` entirely.
  *
  * Unknown flags are an error, not silently ignored — `timber dev --port 4000`
- * starting on the default port would contradict fail-loudly. The CLI surface
- * is intentionally --config-only (design/11-platform.md §CLI); port selection
- * goes through the PORT env var or server.port in vite.config.ts.
+ * starting on the default port would contradict fail-loudly. The surface stays
+ * deliberately small (design/11-platform.md §CLI); port selection goes through
+ * the PORT env var or server.port in vite.config.ts.
  */
 export function parseArgs(args: string[]): ParsedArgs {
   if (args.length === 0) {
@@ -47,6 +68,7 @@ export function parseArgs(args: string[]): ParsedArgs {
   }
 
   let config: string | undefined;
+  let project: string | undefined;
   const rest: string[] = [];
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -55,6 +77,17 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!config) {
         throw new Error('--config requires a path argument');
       }
+    } else if (arg === '--project') {
+      if (command !== 'check') {
+        throw new Error(
+          `--project is only valid for \`timber check\` (it names the tsconfig to type-check). ` +
+            `To point \`timber ${command}\` at a different Vite config, use --config <path>.`
+        );
+      }
+      project = args[++i];
+      if (!project) {
+        throw new Error('--project requires a path argument');
+      }
     } else if (arg.startsWith('-')) {
       const portHint =
         arg === '--port' || arg === '-p'
@@ -62,7 +95,8 @@ export function parseArgs(args: string[]): ParsedArgs {
             'or server.port in vite.config.ts.'
           : '';
       throw new Error(
-        `Unknown option: ${arg}. The timber CLI only accepts --config <path>.${portHint}`
+        `Unknown option: ${arg}. The timber CLI accepts --config <path>` +
+          ` (and --project <path> for \`check\`).${portHint}`
       );
     } else if (command === 'schema' || command === 'init') {
       rest.push(arg);
@@ -71,7 +105,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     }
   }
 
-  return { command: command as Command, config, rest };
+  return { command: command as Command, config, project, rest };
 }
 
 // ─── Command Implementations ─────────────────────────────────────────────────
@@ -160,24 +194,25 @@ export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Pro
 }
 
 /**
- * Validate types and routes without producing build output.
- * Runs tsgo --noEmit for type checking.
+ * Validate routes and types without producing build output.
+ *
+ * Runs the route pass first — resolve the project through Vite, scan it, fail
+ * on proven-fatal convention errors, print warnings, and regenerate the route
+ * types — then `tsgo --noEmit`. Codegen has to precede the type pass: the
+ * generated `.timber/*.d.ts` files are what type `<Link href>` and
+ * `useSegmentParams()`, and a fresh clone has never produced them. See
+ * `cli-check.ts` for the full reasoning.
+ *
+ * `--config` names the **Vite** config, as it does for every other command, so
+ * an app that builds with a custom one is checkable the same way.
+ * `--project` names the tsconfig handed to tsgo.
  */
-export async function runCheck(options: CommandOptions): Promise<void> {
-  const { execFile } = await import('node:child_process');
-
-  await new Promise<void>((resolve, reject) => {
-    const configArgs = options.config ? ['--project', options.config] : [];
-    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {
-      if (stdout) process.stdout.write(stdout);
-      if (stderr) process.stderr.write(stderr);
-      if (err) {
-        reject(new Error(`Type check failed with exit code ${err.code}`));
-      } else {
-        resolve();
-      }
-    });
-  });
+export async function runCheck(options: CommandOptions, _deps?: CheckDeps): Promise<void> {
+  const { checkRoutes, runTypeCheck } = await import('./cli-check.js');
+  const { root } = await checkRoutes({ viteConfigFile: options.config }, _deps);
+  // tsgo runs from the root the route pass resolved, not from cwd — that is
+  // where it just wrote the declarations tsgo has to read.
+  await runTypeCheck({ root, config: options.project }, _deps);
 }
 
 // ─── Schema Subcommand ───────────────────────────────────────────────────────
@@ -305,7 +340,7 @@ export async function runInit(): Promise<void> {
 
 async function main(): Promise<void> {
   const parsed = parseArgs(process.argv.slice(2));
-  const options: CommandOptions = { config: parsed.config };
+  const options: CommandOptions = { config: parsed.config, project: parsed.project };
 
   switch (parsed.command) {
     case 'dev':

package/src/client/browser-entry/action-dispatch.ts

@@ -19,6 +19,7 @@ import { getRouter, getRouterOrNull } from '#client-internal';
 import { setHardNavigating } from '../navigation-root.js';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
 import { markClientStale } from '../stale-client.js';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.js';
 export function setupServerActions(): void {
   setServerCallback(async (id: string, args: unknown[]) => {
     const body = await encodeReply(args);
@@ -32,7 +33,7 @@ export function setupServerActions(): void {
     // Build action request headers. Include deployment ID for version
     // skew detection (TIM-446) — the server rejects stale actions gracefully.
     const actionHeaders: Record<string, string> = {
-      'Accept': 'text/x-component',
+      'Accept': RSC_CONTENT_TYPE,
       'x-rsc-action': id,
     };
     const actionDeploymentId = getClientDeploymentId();

package/src/client/browser-entry/index.ts

@@ -28,11 +28,6 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-// TIM-830: Populate the search-params registry eagerly so <Link> on the
-// client can serialize flat `Partial<T>` values synchronously during
-// render and click handlers. Side-effect-only import.
-// @ts-expect-error — virtual module provided by timber-routing plugin
-import 'virtual:timber-search-params-registry';
 // TIM-932: Populate the codec registry so Link's interpolateParams can
 // use codec.serialize() for URL construction. Side-effect-only import.
 // @ts-expect-error — virtual module provided by timber-routing plugin

package/src/client/error-boundary.tsx

@@ -35,6 +35,12 @@ interface DenyDigest {
   type: 'deny';
   status: number;
   data: unknown;
+  /**
+   * Segment key of the segment that owns the matched deny page, present when
+   * an in-tree catch site matched a file it may not render at its own
+   * position and re-threw to reach the owner. See TIM-1356.
+   */
+  ownerKey?: string;
 }
 
 /** Structured digest returned by RSC onError for RenderError. */
@@ -78,6 +84,12 @@ export interface TimberErrorBoundaryProps {
    * graceful degradation — they must NOT change the HTTP status code.
    */
   isSlotBoundary?: boolean;
+  /**
+   * Segment key of the segment that declared this boundary. Only meaningful
+   * against a deny digest carrying an `ownerKey`. See the decline rule in
+   * `render()` and TIM-1356.
+   */
+  segmentKey?: string;
   children: ReactNode;
 }
 
@@ -209,6 +221,34 @@ export class TimberErrorBoundary extends Component<
       return null;
     }
 
+    // Owner-addressed denies: an in-tree catch site already resolved the
+    // fallback chain and matched a file it may not render at its own
+    // position, so it re-threw to reach the segment that owns that file.
+    // Every boundary but that one declines — otherwise the nearest boundary
+    // whose status filter happens to match catches first and renders the
+    // deny page at its own depth, wrapped in the layouts the hoist existed
+    // to skip, and from a different file than the chain chose. (Boundary
+    // nesting is per-segment `{status} → category → error`; the 4xx chain
+    // runs status files across ALL segments before any error.tsx, so a
+    // leaf error.tsx would otherwise beat a root 404.tsx.)
+    //
+    // Declining is the default: an unkeyed boundary — a slot boundary, or
+    // one from a construction site that builds no deny chains — never
+    // claims a deny addressed to a segment. See TIM-1356.
+    // `typeof === 'string'`, not a null check: the digest is untrusted JSON —
+    // `parseDigest` validates only `type`, and any component can set
+    // `error.digest` itself. A non-string `ownerKey` is unequal to every
+    // boundary's key, so a truthiness test would let one error decline its
+    // way past the entire tree and blank the page, where it would otherwise
+    // have hit the nearest matching boundary.
+    if (
+      parsed?.type === 'deny' &&
+      typeof parsed.ownerKey === 'string' &&
+      parsed.ownerKey !== this.props.segmentKey
+    ) {
+      throw error;
+    }
+
     // If this boundary has a status filter, check whether the error matches.
     // Non-matching errors re-throw so an outer boundary can catch them.
     if (this.props.status != null) {
@@ -272,7 +312,7 @@ export class TimberErrorBoundary extends Component<
         });
       }
       return createElement(this.props.fallbackComponent as never, {
-        error,
+        error: denyError(parsed.status, error),
         digest: null,
         reset: this.reset,
         status: parsed.status,
@@ -312,6 +352,30 @@ function parseDigest(error: Error): ParsedDigest | null {
   return null;
 }
 
+/**
+ * The Error an `error.tsx` serving a deny should receive.
+ *
+ * The error that actually arrives here is React's, not the framework's: a
+ * server-thrown error crossing Flight has its message and name replaced with
+ * a generic redacted string in production, by design. An `error.tsx` written
+ * per the docs branches on `error.message` — so handing it the redacted error
+ * gives it nothing to branch on, while the in-tree path hands the same file a
+ * `DenySignal` named error reading `Access denied with status <N>` (see
+ * `renderDenyEntry`). This reconstructs that shape from the digest, which is
+ * where the status already is.
+ *
+ * Derived from the status alone — no stack, no server data — so it is safe on
+ * the client for the same reason the digest is. See design/13-security.md
+ * §"Errors don't leak", TIM-1081.
+ */
+function denyError(status: number, original: Error): Error {
+  // A dev build may have preserved something more useful than the redaction.
+  if (original.name === 'DenySignal') return original;
+  const error = new Error(`Access denied with status ${status}`);
+  error.name = 'DenySignal';
+  return error;
+}
+
 /**
  * Extract the HTTP status code from a parsed digest or error message.
  * Falls back to message pattern matching for errors without a digest.

package/src/client/index.ts

@@ -75,11 +75,22 @@ export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selec
 export { useActionState, useFormAction } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
-// Params — raw hook for untyped access. For typed params, use defineSegmentParams().useSegmentParams().
+// Params. Called with no argument this returns the untyped accumulated params;
+// pass the route's SEGMENT_PATH (from its generated `./$segment` module) to get
+// the exact types `app/schema.ts` declares — `useSegmentParams(SEGMENT_PATH)`.
 export { useSegmentParams } from './use-segment-params';
 
-// Query states — useQueryStates lives on defineSearchParams().useQueryStates()
-// and is available via direct import for advanced cases.
+// Query states. `definition.useQueryStates()` is the usual form; this standalone
+// export is the inline codec-map form, for shared param bundles reused across
+// routes (design/23-search-params.md §"Client Access").
+//
+// Until TIM-1341 this export did not exist, yet four doc sites told users to
+// import it from here. It type-checked only because the generated `.d.ts`
+// augmented this module with a `useQueryStates` overload — so TypeScript
+// believed in a binding that was never emitted, and the documented import
+// failed at build time. Deleting that overload removed the lie; exporting the
+// hook makes the docs true.
+export { useQueryStates } from './use-query-states';
 
 // Cookies — useCookie lives on defineCookie().useCookie().
 // Types still exported for advanced use.

package/src/client/link.tsx

@@ -14,7 +14,8 @@
 // Typed Link: design/09-typescript.md §"Typed Link"
 // - href validated against known routes (via codegen overloads, not runtime)
 // - params prop typed per-route, URL interpolated at runtime
-// - searchParams prop serialized via SearchParamsDefinition
+// - searchParams prop is a query string (from `definition.buildSearchParams()`)
+//   or a plain object whose values are String()-coerced
 // - params and fully-resolved string href are mutually exclusive
 // - searchParams and inline query string are mutually exclusive
 
@@ -25,8 +26,6 @@ import {
   type ReactNode,
   type MouseEvent as ReactMouseEvent,
 } from 'react';
-import type { SearchParamsDefinition } from '../search-params/define.js';
-import { getSearchParamsDefinition } from '../search-params/registry.js';
 import type { LinkFunction } from './index.js';
 import { classifyUrlSegment, type UrlSegment } from '../routing/segment-classify.js';
 import {
@@ -131,26 +130,37 @@ export type LinkSegmentParams<T> = {
 
 // ─── searchParams prop shapes ────────────────────────────────────
 //
-// Per-route Link overloads (emitted by codegen) pass the flat values shape:
-//     searchParams={{ page: 2, q: 'boots' }}
-// The framework looks up the route's SearchParamsDefinition from the
-// search-params registry at runtime (see TIM-830).
+// Two shapes, discriminated at runtime by `typeof === 'string'`:
 //
-// The catch-all overload in client/index.ts (external/computed hrefs)
-// additionally accepts the legacy wrapped shape:
-//     searchParams={{ definition: def, values: { page: 2 } }}
-// because there is no way to look up a definition from a computed string.
+//   1. Codec-aware (preferred) — a query string built from a definition:
+//        searchParams={productParams.buildSearchParams({ page: 2, search: 'boots' })}
+//      `buildSearchParams` applies each codec, honours `withUrlKey` aliases,
+//      and omits values equal to their default. It is typed `Partial<T>` at
+//      the call site, so the definition supplies the type checking.
 //
-// `resolveHref` discriminates at runtime by presence of a `definition` key.
+//   2. Plain object (escape hatch) — every value is String()-coerced:
+//        searchParams={{ ref: 'email' }}
+//      No codecs, no aliases. This is for one-off params that have no
+//      definition. Passing a *definition's* keys this way is a mistake the
+//      types cannot catch: `{ search: 'x' }` emits `?search=x`, where the
+//      definition would emit `?q=x`. Prefer (1) whenever a definition exists.
+//
+// Why a STRING and not a URLSearchParams: a Link is routinely rendered by a
+// Server Component, so this prop crosses the RSC Flight boundary before the
+// client Link runs. `URLSearchParams` is iterable, and React serializes any
+// iterable as an array — so the prop arrived as `[['pg','2'], …]`, fell into
+// the plain-object branch, and rendered `?0=pg&0=2`. Strings survive Flight
+// unchanged. (Codex P1 on PR #1021; reproduced against a live dev server.)
+//
+// TIM-1343 removed the third shape — a flat values object resolved against a
+// runtime registry keyed by href. It required scanning a `params.ts`
+// convention file, a generated registry module, and eager imports of every
+// route's definition into all three entries, to save one `.buildSearchParams`
+// call. See design/23-search-params.md §"Link Integration".
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ParamValue = string | number | string[] | { toString(): string; [key: string]: any };
 
-type WrappedSearchParamsProp = {
-  definition: SearchParamsDefinition<Record<string, unknown>>;
-  values: Record<string, unknown>;
-};
-type FlatSearchParamsProp = Record<string, unknown>;
-type LinkSearchParamsProp = WrappedSearchParamsProp | FlatSearchParamsProp;
+type LinkSearchParamsProp = string | Record<string, unknown>;
 
 /**
  * Runtime-only loose props used internally by the Link implementation.
@@ -303,16 +313,35 @@ export function interpolateParams(pattern: string, params: Record<string, ParamV
  *
  * Handles:
  * - params interpolation into route patterns
- * - searchParams serialization via SearchParamsDefinition
+ * - searchParams serialization (see the two shapes documented above)
  * - Validation that searchParams and inline query strings are exclusive
  */
 /**
- * Runtime discriminator: treat `searchParams` as the legacy wrapped shape
- * only when it literally has a `definition` key. Everything else is the
- * flat `Partial<T>` values shape (TIM-830).
+ * Tolerate a leading '?'. `buildSearchParams()` never emits one, but callers
+ * hand-rolling a query string reasonably might, and silently producing
+ * `?%3Fa=b` for it would be a worse failure than accepting both.
+ */
+function stripLeadingQuestionMark(qs: string): string {
+  return qs.startsWith('?') ? qs.slice(1) : qs;
+}
+
+/**
+ * Escape-hatch serialization for a plain object: String()-coerce every
+ * value, append arrays as repeated keys, skip null/undefined.
+ *
+ * Deliberately codec-free and alias-free — see the shape docs above.
  */
-function isWrappedSearchParamsProp(sp: LinkSearchParamsProp): sp is WrappedSearchParamsProp {
-  return 'definition' in sp;
+function coerceToQueryString(values: Record<string, unknown>): string {
+  const usp = new URLSearchParams();
+  for (const [key, val] of Object.entries(values)) {
+    if (val === undefined || val === null) continue;
+    if (Array.isArray(val)) {
+      for (const item of val) usp.append(key, String(item));
+    } else {
+      usp.set(key, String(val));
+    }
+  }
+  return usp.toString();
 }
 
 export function resolveHref(
@@ -337,46 +366,18 @@ export function resolveHref(
       );
     }
 
-    let definition: SearchParamsDefinition<Record<string, unknown>> | undefined;
-    let values: Record<string, unknown>;
-
-    if (isWrappedSearchParamsProp(searchParams)) {
-      // Legacy wrapped shape — used by the catch-all overload for
-      // computed/external hrefs where no route lookup is possible.
-      definition = searchParams.definition;
-      values = searchParams.values;
-    } else {
-      // Flat shape (TIM-830): look up the definition from the runtime
-      // registry using the un-interpolated href pattern (e.g. '/products/[id]').
-      // The search-params registry is populated eagerly at startup by the
-      // virtual:timber-search-params-registry module generated by the
-      // timber-routing Vite plugin.
-      definition = getSearchParamsDefinition(href) as
-        | SearchParamsDefinition<Record<string, unknown>>
-        | undefined;
-      values = searchParams;
-    }
-
-    if (definition) {
-      const qs = definition.serialize(values);
-      if (qs) {
-        resolvedPath = `${resolvedPath}?${qs}`;
-      }
-    } else {
-      // No registered definition — serialize flat object as plain query params.
-      const usp = new URLSearchParams();
-      for (const [key, val] of Object.entries(values)) {
-        if (val === undefined || val === null) continue;
-        if (Array.isArray(val)) {
-          for (const item of val) usp.append(key, String(item));
-        } else {
-          usp.set(key, String(val));
-        }
-      }
-      const qs = usp.toString();
-      if (qs) {
-        resolvedPath = `${resolvedPath}?${qs}`;
-      }
+    // A string is already a serialized query (from
+    // `definition.buildSearchParams()`), so it passes through untouched.
+    // `typeof` is the only discriminator that survives the RSC Flight
+    // boundary — see the shape docs above for what happened when this was
+    // an object test.
+    const qs =
+      typeof searchParams === 'string'
+        ? stripLeadingQuestionMark(searchParams)
+        : coerceToQueryString(searchParams);
+
+    if (qs) {
+      resolvedPath = `${resolvedPath}?${qs}`;
     }
   }
 

package/src/client/navigation-commit.ts

@@ -38,6 +38,22 @@ export interface NavigationCommitInput {
   /** When true, clear the segment cache if segmentInfo is absent
    *  (popstate replay for entries without layout metadata). */
   clearSegmentCacheOnEmpty?: boolean;
+  /**
+   * HTTP status of the response this navigation rendered, when it came from a
+   * fetch. Omitted by replays, which re-publish a tree already judged.
+   *
+   * An error response rendered a status page, and a status page replaces a
+   * subtree: the deny page lands at the segment owning the matched file and
+   * nothing below it mounts. `segmentInfo` nonetheless describes the whole
+   * chain the payload was built against — it must, because the merge point is
+   * chosen out of it — so the cache has to be told not to learn from this one.
+   *
+   * Enforced here rather than at the call sites because there are three of
+   * them (`performNavigationFetch`, `refresh()`, and uncached traversal, the
+   * last two through `fetchCommitAndRender`) and only one had the check.
+   * See TIM-1356.
+   */
+  status?: number;
 }
 
 /**
@@ -151,12 +167,19 @@ export function createNavigationCommitter(deps: {
     prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation {
       const navState = deriveNavigationState(url);
 
+      // A tree rendered by an error response is not one to cache — see
+      // `status` on NavigationCommitInput. Normalized here, once, so no fetch
+      // caller can forget it; the history entry records the same thing, or a
+      // traversal back to this URL would replay the metadata this drops.
+      const cacheable = opts.status === undefined || opts.status < 400;
+      const segmentInfo = cacheable ? opts.segmentInfo : [];
+
       return {
         navState,
         commit() {
-          if (opts.segmentInfo && opts.segmentInfo.length > 0) {
-            updateSegmentCache(opts.segmentInfo);
-          } else if (opts.segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) {
+          if (segmentInfo && segmentInfo.length > 0) {
+            updateSegmentCache(segmentInfo);
+          } else if (segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) {
             segmentCache.clear();
           }
 
@@ -165,7 +188,7 @@ export function createNavigationCommitter(deps: {
           historyStack.push(url, {
             payload: opts.payload,
             params: opts.params,
-            segmentInfo: opts.segmentInfo,
+            segmentInfo,
           });
         },
       };

package/src/client/params-context.ts

@@ -64,10 +64,10 @@ export type ParamsContextValue = PublishedParams;
  * do it: React's `react-server` export provides neither `createContext` nor
  * `useContext`, and a *named* ESM import of a missing export fails at module
  * instantiation — before any feature check could run. This module is reachable
- * from `@timber-js/app/segment-params`, which a Server Component imports for
- * `defineSegmentParams`, so the named form crashed that entry outright
- * (codex, PR #992; reproduced with
- * `node --conditions react-server -e "import('./dist/segment-params/index.js')"`).
+ * from every entry a Server Component imports, so the named form crashed
+ * those entries outright (codex, PR #992; originally reproduced against
+ * `@timber-js/app/segment-params`, an entry point since deleted by TIM-1342 —
+ * the hazard is unchanged for the entries that remain).
  *
  * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
  */

package/src/client/router-pipeline.ts

@@ -314,6 +314,9 @@ export function createNavigationPipeline({
           decodePromise: prefetched.decodePromise ?? null,
           segmentInfo: prefetched.segmentInfo ?? null,
           skippedSegments: prefetched.skippedSegments ?? null,
+          // Entries written before this field carried it are treated as
+          // cacheable, which is what they were before a deny could be one.
+          status: prefetched.status ?? 200,
         }
       : undefined;
 
@@ -364,6 +367,7 @@ export function createNavigationPipeline({
       payload: isPartial || hasSkippedSlots ? null : payload,
       params,
       segmentInfo: result.segmentInfo,
+      status: result.status,
     });
 
     return {

package/src/client/router.ts

@@ -218,6 +218,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
               payload,
               params,
               segmentInfo: result.segmentInfo,
+              status: result.status,
             });
             return { ...result, payload, params, navState, commit };
           });

package/src/client/rsc-fetch.ts

@@ -27,6 +27,7 @@ import { normalizeBasePath, stripBasePath, withBasePath } from '../shared/base-p
 import { rscPayloadPath } from '../shared/rsc-payload-path.js';
 import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
 import { TIMBER_ERROR_HEADER } from '../shared/rsc-error-envelope.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 import type { RouterDeps } from './router-types.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -57,12 +58,17 @@ export interface FetchResult {
   segmentInfo: SegmentInfo[] | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
+  /**
+   * HTTP status of the navigation response.
+   *
+   * Read at the commit site to decide whether the tree this payload produced
+   * is one worth caching. A deny page replaced a subtree, so `segmentInfo`
+   * describes more than actually mounted — but it cannot simply be emptied,
+   * because the merge point is chosen out of it. See TIM-1356.
+   */
+  status: number;
 }
 
-// ─── Constants ───────────────────────────────────────────────────
-
-export const RSC_CONTENT_TYPE = 'text/x-component';
-
 // ─── URL Helpers ─────────────────────────────────────────────────
 
 /**
@@ -531,6 +537,7 @@ export async function fetchRscPayload(
     const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
     let segmentInfo: SegmentInfo[] | null = null;
     let skippedSegments: string[] | null = null;
+    let status = 200;
     // Track when the full RSC body stream is consumed (not just shell).
     // Initialized to resolved for bodyless responses; overwritten when
     // the response has a body.
@@ -586,6 +593,7 @@ export async function fetchRscPayload(
       // as React elements — React 19 Float handles them. See TIM-1151.
       segmentInfo = extractSegmentInfo(response);
       skippedSegments = extractSkippedSegments(response);
+      status = response.status;
 
       // Wrap the body to track full stream consumption. createFromFetch's
       // thenable resolves when the root model (shell) arrives, but we need
@@ -634,6 +642,7 @@ export async function fetchRscPayload(
       decodePromise,
       segmentInfo,
       skippedSegments,
+      status,
     };
   }
   // Test/fallback path: return raw text
@@ -677,5 +686,6 @@ export async function fetchRscPayload(
     decodePromise: null,
     segmentInfo: extractSegmentInfo(response),
     skippedSegments: extractSkippedSegments(response),
+    status: response.status,
   };
 }

package/src/client/segment-cache.ts

@@ -26,6 +26,14 @@ export interface PrefetchResult {
   params?: PublishedParams | Promise<PublishedParams>;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;
+  /**
+   * HTTP status of the prefetched response. A deny payload is an ordinary
+   * Flight response carrying a 4xx, so it prefetches and caches like any
+   * other — and the tree it renders is one the segment cache must not learn
+   * from. Absent on entries that predate the field, and on the negative
+   * sentinel. See TIM-1356.
+   */
+  status?: number;
 }
 
 /**