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

package/src/server/ssr-entry.ts

@@ -14,10 +14,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> rendered
-// during SSR can serialize flat `Partial<T>` values via registry lookup.
-// @ts-expect-error — virtual module provided by timber-routing plugin
-import 'virtual:timber-search-params-registry';
 // TIM-949: Populate the codec registry so server-rendered <Link> components
 // use codec.serialize() instead of String() fallback for URL interpolation.
 // @ts-expect-error — virtual module provided by timber-routing plugin
@@ -45,6 +41,7 @@ import { wrapSsrElement } from './ssr-wrappers.js';
 import { withSpan } from './tracing.js';
 import { setCurrentParams } from '../client/use-segment-params.js';
 import { registerSsrDataProvider, type SsrData } from '../client/ssr-data.js';
+import { readPayloadTree } from '../shared/payload-root.js';
 import type { NavContext } from './ssr-bridge-types.js';
 
 // Pre-import Node.js stream modules at module load time — not per-request.
@@ -129,6 +126,7 @@ export async function handleSsr(
       searchParams: navContext.searchParams,
       cookies: navContext.cookies ?? new Map(),
       params: navContext.segmentParams,
+      slotParams: navContext.slotParams,
       _navContext: navContext,
     };
 
@@ -154,19 +152,25 @@ export async function handleSsr(
       // On Node.js: convert Web ReadableStream → Node Readable → createFromNodeStream
       //   (eliminates Promise-per-chunk overhead from Web Streams reader)
       // On Workers: createFromReadableStream (Web Streams are V8-native C++ there)
-      let element: React.ReactNode;
+      let root: unknown;
       if (hasNodeStreamDecode && _nodeStreamImports) {
         const nodeRscStream = _nodeStreamImports.ReadableFromWeb(
           rscStream as import('stream/web').ReadableStream
         );
-        element = createFromNodeStream(nodeRscStream) as React.ReactNode;
+        root = createFromNodeStream(nodeRscStream);
       } else {
-        element = createFromReadableStream(rscStream) as React.ReactNode;
+        root = createFromReadableStream(rscStream);
       }
+      // The payload root is `{ tree, params, slotParams }` — params ride
+      // beside the tree rather than in a provider around it (TIM-1297). SSR
+      // renders the tree; the params it needs are already in `ssrData` above,
+      // which is where `useSegmentParams()` reads them from during SSR. The
+      // client renders its own provider over the same records.
+      const element = Promise.resolve(root).then(readPayloadTree) as React.ReactNode;
       const _decodeEnd = performance.now();
 
       // Wrap with the same component tree structure as the client hydration
-      // tree (NavigationRoot → PendingNavigationProvider → TopLoader →
+      // tree (NavigationRoot → TopLoader →
       // TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider).
       // This ensures useId() produces matching IDs on both sides, preventing
       // hydration mismatches in libraries like Radix UI. See TIM-532.
@@ -228,8 +232,11 @@ export async function handleSsr(
         // stage: pipeline() destroys every stage on failure, so only an
         // output kept outside the pipeline can append the noindex script
         // and close cleanly (TIM-1019).
+        // Resolve the lazy segment script now that the shell is ready
+        // (AccessGates have settled, ALS deny index is authoritative).
+        const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
         const bufferedTransform = createNodeBufferedTransform();
-        const headInjector = createNodeHeadInjector(navContext.headHtml);
+        const headInjector = createNodeHeadInjector(resolvedHeadHtml);
         const flightInjector = createNodeFlightInjector(navContext.rscStream, {
           renderTimeoutMs,
           errorSignal: navContext._errorSignal,
@@ -288,8 +295,11 @@ export async function handleSsr(
       // HTML fragments so downstream transforms never see chunk boundaries
       // mid-tag. This prevents RSC script injection from breaking HTML
       // structure (TIM-527).
+      // Resolve the lazy segment script now that the shell is ready
+      // (AccessGates have settled, ALS deny index is authoritative).
+      const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
       let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
-      outputStream = injectHead(outputStream, navContext.headHtml);
+      outputStream = injectHead(outputStream, resolvedHeadHtml);
       outputStream = injectRscPayload(
         outputStream,
         navContext.rscStream,

package/src/server/ssr-wrappers.tsx

@@ -8,13 +8,26 @@
  * Radix UI that rely on useId() internally.
  *
  * The client tree (browser-entry.ts) wraps the RSC element with:
- *   NavigationRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
+ *   NavigationRoot → Fragment(TopLoader, ...) →
  *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
  *
  * The SSR tree must produce the same component boundaries. These wrappers
  * are no-op components that render children directly but exist as fiber
  * nodes to match the client's tree depth.
  *
+ * **What actually shifts an id is a fork, not depth.** `useId` derives from
+ * React's tree context, which only changes where a fiber has more than one
+ * child — here, `Fragment(TopLoader, element)`. A single-child wrapper, plain
+ * component or context provider, leaves every id below it unchanged; that is
+ * verified, not assumed. So the client-only wrappers that take exactly one
+ * child — `SegmentUpdateContext.Provider`, and `PayloadRoot` with the params
+ * provider it renders (TIM-1297) — have no mirror here and need none. Mirror a
+ * new wrapper only if it branches.
+ *
+ * `PendingNavigationProvider` and its `SsrPendingProvider` mirror were both
+ * deleted with the dead pending context (TIM-1307). Removing them shifts no
+ * id: it was a single-child provider, the case the rule above covers.
+ *
  * Related issues: facebook/react#24669, radix-ui/primitives#3700
  * See design/02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
  */
@@ -25,11 +38,13 @@ import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
 /**
  * SSR equivalent of NavigationRoot.
  *
- * On the client, NavigationRoot uses useState and standalone startTransition, rendering:
- *   PendingNavigationProvider(Fragment(TopLoader, element))
+ * On the client, NavigationRoot uses useState and standalone startTransition,
+ * rendering `Fragment(TopLoader, element)` — or the element alone when the top
+ * loader is disabled.
  *
- * This SSR version matches the component boundary depth without client
- * hooks. It renders SsrPendingProvider → Fragment(SsrTopLoader, children).
+ * The Fragment is the part that matters: it forks, so it advances React's tree
+ * context. Both sides must agree on whether it is there, which is why
+ * `hasTopLoader` is threaded in from the same config the client reads.
  */
 function SsrNavigationRoot({
   children,
@@ -39,20 +54,8 @@ function SsrNavigationRoot({
   hasTopLoader: boolean;
 }): ReactNode {
   if (hasTopLoader) {
-    return createElement(
-      SsrPendingProvider,
-      null,
-      createElement(Fragment, null, createElement(SsrTopLoader, null), children)
-    );
+    return createElement(Fragment, null, createElement(SsrTopLoader, null), children);
   }
-  return createElement(SsrPendingProvider, null, children);
-}
-
-/**
- * SSR equivalent of PendingNavigationProvider.
- * Matches the context.Provider component boundary on the client.
- */
-function SsrPendingProvider({ children }: { children: ReactNode }): ReactNode {
   return children as ReactNode;
 }
 
@@ -98,21 +101,19 @@ function SsrNuqsWrapper({
  *
  * Client tree (browser-entry.ts):
  *   NavigationRoot
- *     → PendingNavigationProvider
- *       → Fragment(TopLoader, element)
- *         → TimberNuqsAdapter
- *           → NuqsAdapterProvider (from createAdapterProvider)
- *             → NavigationProvider
- *               → [RSC element]
+ *     → Fragment(TopLoader, element)
+ *       → TimberNuqsAdapter
+ *         → NuqsAdapterProvider (from createAdapterProvider)
+ *           → NavigationProvider
+ *             → [RSC element]
  *
  * SSR tree (this function):
  *   SsrNavigationRoot
- *     → SsrPendingProvider
- *       → Fragment(SsrTopLoader, element)
- *         → SsrNuqsWrapper
- *           → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
- *             → SsrNavigationProvider
- *               → [RSC element]
+ *     → Fragment(SsrTopLoader, element)
+ *       → SsrNuqsWrapper
+ *         → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
+ *           → SsrNavigationProvider
+ *             → [RSC element]
  *
  * @param element - The decoded RSC element
  * @param searchParams - Request search params for nuqs SSR adapter
@@ -126,7 +127,7 @@ export function wrapSsrElement(
   // Build inside-out to match the client's createElement chain:
   //   NavigationProvider(TimberNuqsAdapter(element))
   //   → passed as initial to NavigationRoot
-  //   → NavigationRoot renders PendingNavigationProvider(Fragment(TopLoader, initial))
+  //   → NavigationRoot renders Fragment(TopLoader, initial)
 
   // 1. Innermost: NavigationProvider equivalent
   const withNav = createElement(SsrNavigationProvider, null, element);
@@ -135,7 +136,7 @@ export function wrapSsrElement(
   // eslint-disable-next-line react/no-children-prop -- createElement API
   const withNuqs = createElement(SsrNuqsWrapper, { searchParams, children: withNav });
 
-  // 3. Outermost: NavigationRoot equivalent (PendingNavigationProvider + TopLoader)
+  // 3. Outermost: NavigationRoot equivalent (the TopLoader fork)
   // eslint-disable-next-line react/no-children-prop -- createElement API
   return createElement(SsrNavigationRoot, { hasTopLoader, children: withNuqs });
 }

package/src/server/state-tree-diff.ts

@@ -18,64 +18,17 @@ import { swallow } from './logger.js';
 import { matchUrlParts } from './tree-match.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 
-// ─── Segment Key Computation ─────────────────────────────────────
-
-/**
- * Segment node shape expected by computeSegmentKeys.
- * Matches the relevant fields from ManifestSegmentNode without
- * importing it (avoids circular deps from routing → server).
- */
-interface SegmentKeyInput {
-  urlPath: string;
-  segmentName?: string;
-  segmentType?: string;
-}
-
-/**
- * Compute state-tree keys for a segment chain.
- *
- * Non-group segments use their urlPath as-is. Route groups accumulate
- * ancestor group names to produce globally unique keys:
- *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']
- *
- * This is the single source of truth for segment keys — used by the
- * element builder (skip decisions, SegmentOutlet props), segment info
- * (X-Timber-Segments header), and the client cache/state tree.
- */
-export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
-  const keys: string[] = [];
-  let prevKey = '';
-
-  for (const segment of segments) {
-    if (segment.segmentType === 'group') {
-      const base = prevKey === '/' ? '' : prevKey;
-      const key = `${base}/${segment.segmentName}`;
-      keys.push(key);
-      prevKey = key;
-    } else {
-      keys.push(segment.urlPath);
-      prevKey = segment.urlPath;
-    }
-  }
-
-  return keys;
-}
-
-/**
- * Compute a unique key for a parallel route slot.
- * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
- */
-export function computeSlotKey(parentSegmentId: string, slotName: string): string {
-  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
-  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
-  return `${prefix}/${name}`;
-}
-
 // ─── State Tree Parsing ──────────────────────────────────────────
 
 /** Parsed client state tree with segment paths and optional slot paths. */
 export interface ClientStateTree extends Set<string> {
   slots?: Set<string> | null;
+  /**
+   * `app/` directory paths of the segments currently mounted on the client.
+   * Read only by interception scoping — never by the skip decisions.
+   * See design/07-routing.md §"Intercepting Routes" (TIM-1282).
+   */
+  treePaths?: Set<string> | null;
 }
 
 /**
@@ -93,14 +46,20 @@ export function parseClientStateTree(req: Request): ClientStateTree | null {
   if (!header) return null;
 
   try {
-    const parsed = JSON.parse(header) as { segments?: unknown; slots?: unknown };
+    const parsed = JSON.parse(header) as {
+      segments?: unknown;
+      slots?: unknown;
+      treePaths?: unknown;
+    };
     const hasSegments = Array.isArray(parsed.segments) && parsed.segments.length > 0;
     const hasSlots = Array.isArray(parsed.slots) && parsed.slots.length > 0;
-    if (!hasSegments && !hasSlots) {
+    const hasTreePaths = Array.isArray(parsed.treePaths) && parsed.treePaths.length > 0;
+    if (!hasSegments && !hasSlots && !hasTreePaths) {
       return null;
     }
     const result = new Set(hasSegments ? (parsed.segments as string[]) : []) as ClientStateTree;
     result.slots = hasSlots ? new Set(parsed.slots as string[]) : null;
+    result.treePaths = hasTreePaths ? new Set(parsed.treePaths as string[]) : null;
     return result;
   } catch (err) {
     swallow(err, 'malformed X-Timber-State-Tree header');

package/src/server/static-generator.ts

@@ -23,6 +23,13 @@ import type { ManifestRoot, ManifestSegmentNode, ManifestFile } from './route-ma
 import { hasDynamicSegments, hasUserSitemap, resolvePathWithParams } from './sitemap-generator.js';
 import { loadModule } from './safe-load.js';
 import { METADATA_ROUTE_CONVENTIONS, resolveServePathForFile } from './metadata-routes.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+import {
+  NOT_FOUND_ENTRY_PATH,
+  NOT_FOUND_PROBE_PATH,
+  resolveNotFoundPage,
+  type NotFoundProbe,
+} from './static-not-found.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -70,6 +77,12 @@ export interface StaticGenerationSummary {
   errors: StaticGenerationError[];
   /** Redirects from middleware/proxy that need platform redirect rules. */
   redirects: StaticRedirectEntry[];
+  /**
+   * Non-fatal problems the build should surface. Unlike `errors`, these do not
+   * fail the build — they name a degraded outcome the developer can act on
+   * (e.g. the not-found probe answering with something other than a 404).
+   */
+  warnings: string[];
 }
 
 export interface StaticGenerationOptions {
@@ -211,7 +224,22 @@ export async function enumerateStaticUrls(
 
   await walk(root);
   urls.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
-  return { urls, errors };
+
+  // Drop repeats of the same (path, kind). `generateStaticSegmentParams` is
+  // an application function returning whatever a CMS query gave it, and a
+  // repeated combo asks for the same page twice — identical bytes to the same
+  // file, so it is waste rather than ambiguity. Removing it here keeps the
+  // output-path collision check (TIM-1266) meaning what it says: two
+  // *different* routes competing for one file.
+  const seen = new Set<string>();
+  const unique = urls.filter(({ urlPath, kind }) => {
+    const key = `${kind}:${urlPath}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  return { urls: unique, errors };
 }
 
 /**
@@ -401,7 +429,18 @@ export async function generateStaticSite(
 ): Promise<StaticGenerationSummary> {
   const log = options.log ?? ((msg: string) => console.log(msg));
   const timeoutMs = options.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
-  const summary: StaticGenerationSummary = { rendered: 0, errors: [], redirects: [] };
+  const summary: StaticGenerationSummary = {
+    rendered: 0,
+    errors: [],
+    redirects: [],
+    warnings: [],
+  };
+  // Warnings are recorded and logged from one place so the summary the build
+  // reports and the line the developer reads can never describe different sets.
+  const warn = (message: string) => {
+    summary.warnings.push(message);
+    log(`[timber] Static generation: ${message}`);
+  };
 
   log('[timber] Static generation: enumerating routes…');
 
@@ -477,7 +516,7 @@ export async function generateStaticSite(
       // success so a transient write error doesn't orphan the flight file.
       if (htmlOk) {
         try {
-          const rscResponse = await renderUrl(handler, urlPath, 'text/x-component', timeoutMs);
+          const rscResponse = await renderUrl(handler, urlPath, RSC_CONTENT_TYPE, timeoutMs);
 
           if (rscResponse.status < 400) {
             await options.onEntry({
@@ -485,7 +524,7 @@ export async function generateStaticSite(
               status: rscResponse.status,
               headers: headersToRecord(rscResponse.headers),
               body: rscResponse.body,
-              contentType: rscResponse.headers.get('content-type') ?? 'text/x-component',
+              contentType: rscResponse.headers.get('content-type') ?? RSC_CONTENT_TYPE,
               kind: 'rsc',
             });
             summary.rendered++;
@@ -548,34 +587,34 @@ export async function generateStaticSite(
     }
   }
 
-  // Render 404.html — the app's not-found page for unmatched URLs.
-  // Static hosts (GitHub Pages, Cloudflare Pages, Netlify) serve this
-  // automatically when no matching file exists.
-  // Uses /_timber/__not_found as the probe path: _timber/ is the framework's
-  // reserved prefix and __not_found is a private segment (double underscore),
-  // so user routes (including catch-all [..slug]) cannot claim this path.
+  // Write 404.html. Always — the classification of what to write, and what
+  // to tell the developer about it, lives in static-not-found.ts.
+  let probe: NotFoundProbe;
   try {
-    const notFoundResponse = await renderUrl(
-      handler,
-      '/_timber/__not_found',
-      'text/html',
-      timeoutMs
-    );
-    if (notFoundResponse.status === 404 && notFoundResponse.body.byteLength > 0) {
-      await options.onEntry({
-        urlPath: '/_timber_not_found',
-        status: notFoundResponse.status,
-        headers: headersToRecord(notFoundResponse.headers),
-        body: notFoundResponse.body,
-        contentType: notFoundResponse.headers.get('content-type') ?? 'text/html',
-        kind: 'html',
-      });
-      log('[timber] Static generation: rendered 404.html');
-    }
-  } catch {
-    log('[timber] Static generation: 404 page render failed — skipping 404.html');
+    const response = await renderUrl(handler, NOT_FOUND_PROBE_PATH, 'text/html', timeoutMs);
+    probe = {
+      kind: 'response',
+      status: response.status,
+      body: response.body,
+      headers: headersToRecord(response.headers),
+      contentType: response.headers.get('content-type') ?? 'text/html',
+    };
+  } catch (error) {
+    probe = { kind: 'threw', error };
   }
 
+  const notFound = resolveNotFoundPage(probe, manifest.root);
+  if (notFound.warning) warn(notFound.warning);
+  await options.onEntry({
+    urlPath: NOT_FOUND_ENTRY_PATH,
+    status: 404,
+    headers: notFound.headers,
+    body: notFound.body,
+    contentType: notFound.contentType,
+    kind: 'html',
+  });
+  log(notFound.logLine);
+
   // Discover and render paginated sub-sitemaps. If /sitemap.xml was an
   // index (contains /sitemap/N.xml references), render each sub-sitemap.
   if (options.autoSitemapEnabled && !hasUserSitemap(manifest.root)) {

package/src/server/static-not-found.ts

@@ -0,0 +1,134 @@
+/**
+ * 404.html generation for static builds.
+ *
+ * `404.html` is written unconditionally (design/11-platform.md item 7). When
+ * the not-found probe does not produce a usable page, the framework default
+ * status page is written instead and the reason is reported as a warning —
+ * a static deploy that silently shipped no 404 page fell back to the host's
+ * generic one, and nothing in the build output said so (TIM-1258).
+ *
+ * The classification lives here, apart from the generation orchestration, so
+ * it can be exercised directly: every branch is a different diagnosis handed
+ * to a developer, and a wrong one sends them to the wrong file.
+ */
+
+import { resolveStatusFile } from './status-code-resolver.js';
+import { DEFAULT_STATUS_PAGE_CONTENT_TYPE, defaultStatusPageHtml } from './default-status-page.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+/**
+ * The probe path. `_timber/` is the framework's reserved prefix and
+ * `__not_found` is a private segment (double underscore), so user routes —
+ * including a catch-all `[...slug]` — cannot claim it.
+ */
+export const NOT_FOUND_PROBE_PATH = '/_timber/__not_found';
+
+/** URL path the static build maps to `404.html`. See plugins/static-build.ts. */
+export const NOT_FOUND_ENTRY_PATH = '/_timber_not_found';
+
+/** What the probe produced: a response, or the failure that replaced one. */
+export type NotFoundProbe =
+  | {
+      kind: 'response';
+      status: number;
+      body: Uint8Array;
+      headers: Record<string, string>;
+      contentType: string;
+    }
+  | { kind: 'threw'; error: unknown };
+
+export interface NotFoundResult {
+  /** Body to write as `404.html` — never empty. */
+  body: Uint8Array;
+  headers: Record<string, string>;
+  contentType: string;
+  /** Non-fatal problem to report, or null when the app rendered its own page. */
+  warning: string | null;
+  /** Build log line. Names *which* page was written. */
+  logLine: string;
+}
+
+/**
+ * Whether the not-found chain has anything to render for this root.
+ *
+ * Asks the resolver rather than inspecting file names: `renderNoMatchPage`
+ * builds its chain from the root segment alone and resolves through exactly
+ * these two calls, so this cannot drift from what the request path does. A
+ * hand-rolled key check gets it wrong — a root that declares only `500.tsx`
+ * has status files but nothing a 404 can select.
+ */
+function rootDeclaresNotFoundPage(root: ManifestSegmentNode): boolean {
+  return (
+    resolveStatusFile(404, [root], 'component') !== null ||
+    resolveStatusFile(404, [root], 'json') !== null
+  );
+}
+
+/** The framework default page, as a `404.html` payload. */
+function frameworkDefault(warning: string): NotFoundResult {
+  return {
+    body: new TextEncoder().encode(defaultStatusPageHtml(404)),
+    headers: { 'content-type': DEFAULT_STATUS_PAGE_CONTENT_TYPE },
+    contentType: DEFAULT_STATUS_PAGE_CONTENT_TYPE,
+    warning,
+    // Say which page was written — "rendered" would claim the app produced it.
+    logLine: '[timber] Static generation: wrote the framework default 404.html',
+  };
+}
+
+/**
+ * Decide what to write as `404.html`, and what to tell the developer.
+ *
+ * @param probe  What requesting {@link NOT_FOUND_PROBE_PATH} produced.
+ * @param root   Root segment of the route manifest — the only thing that can
+ *               distinguish an absent not-found page from a broken one.
+ */
+export function resolveNotFoundPage(
+  probe: NotFoundProbe,
+  root: ManifestSegmentNode
+): NotFoundResult {
+  if (probe.kind === 'threw') {
+    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
+    return frameworkDefault(
+      `the not-found page failed to render — writing the framework default 404.html. ${message}`
+    );
+  }
+
+  if (probe.status !== 404) {
+    return frameworkDefault(
+      `the not-found probe ${NOT_FOUND_PROBE_PATH} answered ${probe.status}, not 404 — ` +
+        `writing the framework default 404.html instead. A catch-all route or middleware is ` +
+        `claiming unmatched URLs.`
+    );
+  }
+
+  // The pipeline produced nothing, or produced the framework default itself.
+  // Compared by identity against the same builder rather than by a proxy like
+  // "the body is empty", which the default page invalidated.
+  const isDefault =
+    probe.body.byteLength === 0 ||
+    new TextDecoder().decode(probe.body) === defaultStatusPageHtml(404);
+
+  if (isDefault) {
+    // Which of the two it is cannot be read off the response: the deny chain
+    // answers "no status file" and "the status file threw" with the same
+    // bytes. Telling a developer whose 404.tsx just crashed to "add
+    // app/404.tsx" sends them to a file that already exists and buries the
+    // real failure, which the chain logged on its way past.
+    return frameworkDefault(
+      rootDeclaresNotFoundPage(root)
+        ? `the app's not-found page did not render — writing the framework default 404.html. ` +
+            `A root status file exists but produced no page; see the render error logged above.`
+        : `the app has no not-found page — writing the framework default 404.html. ` +
+            `Add app/404.tsx (or 4xx.tsx / error.tsx) to control it.`
+    );
+  }
+
+  return {
+    body: probe.body,
+    headers: probe.headers,
+    contentType: probe.contentType,
+    warning: null,
+    logLine: '[timber] Static generation: rendered 404.html',
+  };
+}

package/src/server/status-code-resolver.ts

@@ -105,16 +105,24 @@ function lookupInGroup<TFile>(
  * @param status - The HTTP status code (4xx or 5xx).
  * @param segments - The matched segment chain from root (index 0) to leaf (last).
  * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
+ * @param maxIndex - Optional upper bound on the segment index to search.
+ *   When set, the resolver only considers segments `0..maxIndex` (inclusive),
+ *   skipping any segments deeper in the tree. Used by the deny renderers to
+ *   prevent resolving a status file below a denied segment — matching
+ *   `buildDenyPageChain`'s start-at-i semantics. The error renderers omit
+ *   this parameter, so the full chain is searched — a 500 from a leaf page
+ *   should use the leaf's own `5xx.tsx`. See TIM-1358.
  */
 export function resolveStatusFile<TFile>(
   status: number,
   segments: ReadonlyArray<SegmentNode<TFile>>,
-  format: StatusFileFormat = 'component'
+  format: StatusFileFormat = 'component',
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   if (status < 400 || status > 599) return null;
-  if (format === 'json') return resolveJson(status, segments);
-  if (status <= 499) return resolve4xx(status, segments);
-  return resolve5xx(status, segments);
+  if (format === 'json') return resolveJson(status, segments, maxIndex);
+  if (status <= 499) return resolve4xx(status, segments, maxIndex);
+  return resolve5xx(status, segments, maxIndex);
 }
 
 /**
@@ -131,16 +139,19 @@ export function resolveStatusFile<TFile>(
  */
 function resolve4xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode<TFile>>
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const r = lookupInGroup(segments[i].statusFiles, statusStr, '4xx', i, status);
     if (r) return r;
   }
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const errorFile = segments[i].error;
     if (errorFile) {
       return { file: errorFile, status, kind: 'error', segmentIndex: i };
@@ -159,11 +170,14 @@ function resolve4xx<TFile>(
  */
 function resolve5xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode<TFile>>
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const segment = segments[i];
     const r = lookupInGroup(segment.statusFiles, statusStr, '5xx', i, status);
     if (r) return r;
@@ -184,12 +198,15 @@ function resolve5xx<TFile>(
  */
 function resolveJson<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode<TFile>>
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
   const categoryKey = status >= 500 ? '5xx' : '4xx';
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
     if (r) return r;
   }