@timber-js/app 0.2.0-alpha.161 → 0.2.0-alpha.164

package/src/server/route-element-builder.ts

@@ -49,7 +49,7 @@ import { ChildSegmentProvider } from '../client/child-segment-provider.js';
 
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
-import { shouldSkipSegment } from './state-tree-diff.js';
+import { shouldSkipSegment, computeSegmentKeys } from './state-tree-diff.js';
 import type { HeadElement } from './metadata.js';
 
 /**
@@ -515,61 +515,96 @@ export async function buildRouteElement(
   // The client uses this to merge the partial payload with its cached segments.
   const skippedSegments: string[] = [];
 
-  // Wrap from innermost (leaf) to outermost (root), processing every
-  // segment in the chain. Each segment may contribute:
-  //   1. Error boundaries (status files + error.tsx)
-  //   2. Layout component — wraps children + parallel slots
-  //   3. SegmentProvider — records position for useSelectedLayoutSegment
+  // Compute state-tree keys for all segments. Route groups accumulate
+  // ancestor group names for globally unique keys (e.g., "/(a)/(shared)"
+  // instead of just "/(shared)"). This is the single key computation —
+  // the same keys are used for skip decisions, SegmentOutlet props, and
+  // the X-Timber-Segments header (via buildSegmentInfo).
+  const segmentKeys = computeSegmentKeys(segments);
+
+  // Pre-compute the contiguous skippable prefix (top-down).
   //
-  // When clientStateTree is provided (from X-Timber-State-Tree header on
-  // client navigation), sync layouts the client already has are skipped.
-  // Access.ts was pre-checked eagerly above for metadata gating (TIM-1027).
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  // Skipped segments must form a contiguous prefix from root to avoid
+  // non-contiguous skips that break the client merge. Walk from root
+  // toward leaf, marking segments as skippable. Stop at the first
+  // segment that can't be skipped (async, not in client tree, leaf).
+  // Layoutless segments are transparent (no outlet, no layout to skip).
   //
-  // hasRenderedLayoutBelow tracks whether a non-skipped layout has been
-  // seen below the current segment. A segment can ONLY be skipped if
-  // there is a rendered layout below it — the client merger can only
-  // replace inner SegmentProviders (client component boundaries), not
-  // page content embedded in a layout's server-rendered output.
-  // Without this guard, skipping the innermost layout causes the merger
-  // to drop the layout entirely and replace it with just the page.
-  let hasRenderedLayoutBelow = false;
+  // After finding the prefix, validate: the first non-skipped layout
+  // must exist in the client's state tree (the client needs a mounted
+  // outlet there to receive the partial payload).
+  const skippableSet = new Set<number>();
+  if (clientStateTree) {
+    for (let i = 0; i < segments.length; i++) {
+      const isLeaf = i === segments.length - 1;
+      const layoutComponent = layoutBySegment.get(segments[i]);
+
+      // Never skip denied segments — their AccessGate must render the
+      // deny page, not reuse the client's cached (passing) layout.
+      if (i >= firstDeniedIndex) break;
+
+      if (shouldSkipSegment(segmentKeys[i], layoutComponent, isLeaf, clientStateTree)) {
+        skippableSet.add(i);
+      } else if (layoutComponent) {
+        break;
+      }
+    }
+
+    // Ensure there's a merge point: a non-skipped layout whose key is
+    // in the client's state tree (so the client has a mounted outlet).
+    // If all layouts are in the prefix, keep the innermost as merge point.
+    if (skippableSet.size > 0) {
+      let mergePointIndex = -1;
+      for (let i = 0; i < segments.length; i++) {
+        if (skippableSet.has(i)) continue;
+        if (layoutBySegment.has(segments[i])) {
+          mergePointIndex = i;
+          break;
+        }
+      }
+
+      if (mergePointIndex === -1) {
+        // All layouts are skippable — keep the innermost as merge point
+        for (let i = segments.length - 1; i >= 0; i--) {
+          if (skippableSet.has(i) && layoutBySegment.has(segments[i])) {
+            skippableSet.delete(i);
+            mergePointIndex = i;
+            break;
+          }
+        }
+      }
+
+      // Cross-section guard: at least one rendered layout below the
+      // prefix must exist in the client's state tree (the client needs
+      // a mounted outlet to receive the partial payload). Check ALL
+      // non-skipped layouts, not just the merge point — async layouts
+      // are excluded from the client state tree but may sit above a
+      // sync layout that IS in the tree.
+      let hasClientOutlet = false;
+      for (let j = 0; j < segments.length; j++) {
+        if (skippableSet.has(j)) continue;
+        if (layoutBySegment.has(segments[j]) && clientStateTree.has(segmentKeys[j])) {
+          hasClientOutlet = true;
+          break;
+        }
+      }
+      if (!hasClientOutlet) {
+        skippableSet.clear();
+      }
+    }
+  }
+
   let outermostSegmentProvider: React.ReactElement | null = null;
-  // Track whether any rendered inner layout also exists in the client's
-  // state tree. This prevents cross-section skipping: e.g., navigating
-  // from /(group-a) to /dashboard shouldn't skip root "/" because the
-  // client has no mounted outlet at "/dashboard".
-  let innerRenderedInClientTree = false;
 
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
     const isLeaf = i === segments.length - 1;
     const layoutComponent = layoutBySegment.get(segment);
 
-    // Check if this segment's layout can be skipped for partial rendering.
-    // Skipped segments: no layout wrapping, no error boundaries, no slots,
-    // no AccessGate in element tree (access already ran pre-render).
-    //
-    // Additional constraints beyond shouldSkipSegment:
-    // - Must have a rendered layout below (so the merger can find an
-    //   inner SegmentProvider to splice the new content into)
-    // - Route groups are never skipped because sibling groups share the
-    //   same urlPath (e.g., /(marketing) and /(app) both have "/"),
-    //   which would cause the wrong cached layout to be reused
-    // - At least one inner rendered layout must exist in the client's
-    //   state tree, ensuring the client has a mounted outlet to receive
-    //   the partial payload
-    const skip =
-      shouldSkipSegment(segment.urlPath, layoutComponent, isLeaf, clientStateTree ?? null) &&
-      hasRenderedLayoutBelow &&
-      segment.segmentType !== 'group' &&
-      innerRenderedInClientTree;
-
-    if (skip) {
-      // Skip this segment's layout/error boundaries — the client uses its cached version.
-      // Metadata was already resolved above (head elements are correct).
+    // Skip decision was pre-computed in the top-down prefix pass.
+    if (skippableSet.has(i)) {
       // Record for X-Timber-Skipped-Segments header (outermost first, so prepend).
-      skippedSegments.unshift(segment.urlPath);
+      skippedSegments.unshift(segmentKeys[i]);
 
       // SECURITY: Even though the layout is skipped, AccessGate MUST still
       // wrap the element tree. access.ts runs on every navigation regardless
@@ -579,9 +614,6 @@ export async function buildRouteElement(
         const accessMod = await loadModule(segment.access);
         const accessFn = accessMod.default as (() => unknown) | undefined;
         if (accessFn) {
-          // Pass verdict for denied/redirected segments so AccessGate replays
-          // without re-execution. Passing segments omit verdict so AccessGate
-          // re-runs access during render for React.cache population.
           const verdict = accessVerdicts.get(i);
           element = h(AccessGate, {
             accessFn,
@@ -596,23 +628,6 @@ export async function buildRouteElement(
       continue;
     }
 
-    // This segment is rendered — mark that future (outer) segments have
-    // a rendered layout below them and can safely be skipped.
-    if (layoutComponent) {
-      hasRenderedLayoutBelow = true;
-      // Use segmentId for the client state tree check. Route groups share
-      // their parent's urlPath (both "/"), but their segmentId includes
-      // the group name (e.g., "/(group-a)"), so the check correctly
-      // fails when the client has never visited that group.
-      const outletKey =
-        segment.segmentType === 'group'
-          ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
-          : segment.urlPath;
-      if (clientStateTree?.has(outletKey)) {
-        innerRenderedInClientTree = true;
-      }
-    }
-
     // Wrap with error boundaries from this segment (inside layout).
     // Keep ALL error boundaries (including 4xx) — they're the safety net for
     // DenySignal from nested server components that escape AccessGate/PageDenyBoundary
@@ -654,13 +669,7 @@ export async function buildRouteElement(
       const segmentPath = rawPath.length === 2 && rawPath[1] === '' ? [''] : rawPath;
       const parallelRouteKeys = Object.keys(segment.slots ?? {});
 
-      // For route groups, urlPath is shared with the parent (both "/"),
-      // so include the group name to distinguish them. Used for both OTEL
-      // span labels and client-side element caching (segmentId).
-      const segmentId =
-        segment.segmentType === 'group'
-          ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
-          : segment.urlPath;
+      const segmentId = segmentKeys[i];
 
       // Build the layout element.
       // Layouts receive <ChildSegmentOutlet /> as children — a stable client

package/src/server/rsc-entry/deny-fallback.ts

@@ -0,0 +1,92 @@
+/**
+ * Deny fallback renderer — renders the deny page (403.tsx, 404.tsx, etc.)
+ * for DenySignals that escape from middleware or the render phase.
+ *
+ * Extracted from index.ts (TIM-968) as a pure move. The factory captures
+ * the root segment and client bootstrap config once at handler creation;
+ * the returned function is wired into `PipelineConfig.renderDenyFallback`
+ * and reused by the action-dispatch wrapper.
+ *
+ * Design docs: 04-authorization.md, 10-error-handling.md
+ */
+
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { ClientBootstrapConfig } from '../html-injectors.js';
+import { logRenderError } from '../logger.js';
+import type { PipelineConfig, RouteMatch } from '../pipeline.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { loadModule } from '../safe-load.js';
+import { createDebugChannelSink, isRscPayloadRequest } from './helpers.js';
+import { callSsr } from './ssr-bridge.js';
+
+/**
+ * Create the pipeline's deny fallback renderer.
+ *
+ * When the pipeline already matched a route (the common case — matching
+ * runs before middleware and rendering), resolve the status file against
+ * the matched chain so colocated files like a nested `403.tsx` or an API
+ * route's `401.json` are picked up. Fall back to the root chain when no
+ * match is available (e.g. proxy-stage deny before route matching).
+ * See TIM-822, design/04-authorization.md, design/10-error-handling.md.
+ */
+export function createDenyFallbackRenderer(options: {
+  rootSegment: ManifestSegmentNode;
+  clientBootstrap: ClientBootstrapConfig;
+}): NonNullable<PipelineConfig['renderDenyFallback']> {
+  const { rootSegment, clientBootstrap } = options;
+  return async (deny, req, responseHeaders, matchedRoute) => {
+    const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [rootSegment];
+    const layoutComponents: LayoutEntry[] = [];
+    try {
+      for (const segment of chain) {
+        if (!segment.layout) continue;
+        const mod = await loadModule(segment.layout);
+        if (mod.default) {
+          layoutComponents.push({
+            component: mod.default as (...args: unknown[]) => unknown,
+            segment,
+          });
+        }
+      }
+    } catch (layoutError) {
+      // Layout failed to load — proceed without it. Partial layout chains
+      // are acceptable; the deny renderer wraps in whatever loaded.
+      logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
+    }
+    // Reuse the matched route's params/middleware metadata when present so
+    // downstream rendering sees the real route shape. Otherwise synthesise
+    // a root-only stub (no params, no middleware).
+    const match: RouteMatch = matchedRoute ?? {
+      segments: chain,
+      segmentParams: {},
+      middlewareChain: [],
+    };
+    // For client navigation (Accept: text/x-component), the timber router
+    // decodes the response as React Flight. Returning HTML to a Flight
+    // decoder breaks navigation, so dispatch to the RSC renderer when the
+    // request is an RSC payload request — mirroring the normal render path.
+    // See design/19-client-navigation.md §"RSC Payload Handling" and TIM-823.
+    if (isRscPayloadRequest(req)) {
+      return renderDenyPageAsRsc(
+        deny,
+        chain,
+        layoutComponents,
+        req,
+        responseHeaders,
+        createDebugChannelSink
+      );
+    }
+    return renderDenyPage(
+      deny,
+      chain,
+      layoutComponents,
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap,
+      createDebugChannelSink,
+      callSsr
+    );
+  };
+}

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

@@ -6,6 +6,7 @@
 
 import type { ManifestSegmentNode } from '../route-matcher.js';
 import { swallow } from '../logger.js';
+import { computeSegmentKeys } from '../state-tree-diff.js';
 
 /** RSC content type for client navigation payload requests. */
 export const RSC_CONTENT_TYPE = 'text/x-component';
@@ -184,19 +185,20 @@ export function buildSegmentInfo(
     layoutComponents.map(({ component, segment }) => [segment, component])
   );
 
+  const segmentKeys = computeSegmentKeys(segments);
   const result: Array<{ path: string; segmentId?: string; isAsync: boolean }> = [];
 
-  for (const segment of segments) {
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
     const component = layoutBySegment.get(segment);
-    const isAsync = component?.constructor?.name === 'AsyncFunction';
-
-    // Compute segmentId — matches the key used by SegmentOutlet.
-    // Route groups share their parent's urlPath, so include the group
-    // name to disambiguate (e.g., "/(marketing)" vs "/").
-    const segmentId =
-      segment.segmentType === 'group'
-        ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
-        : segment.urlPath;
+
+    // Only emit entries for segments with layouts. Layoutless segments
+    // have no SegmentOutlet and must not appear in the client's merge
+    // target search (buildSegmentUpdates).
+    if (!component) continue;
+
+    const isAsync = component.constructor?.name === 'AsyncFunction';
+    const segmentId = segmentKeys[i];
 
     const entry: { path: string; segmentId?: string; isAsync: boolean } = {
       path: segment.urlPath,

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

@@ -12,6 +12,14 @@
  * references. The stream is then passed to the SSR entry (in a separate
  * Vite environment) which decodes it and renders HTML.
  *
+ * This file is intentionally orchestration-only (audited: TIM-968). It
+ * wires virtual modules, config, and one-time startup (cache handler,
+ * instrumentation, CDN purge, prebuilt payload source) into the pipeline
+ * and delegates all rendering work to siblings in this directory
+ * (render-route.ts, error-renderer.ts, deny-fallback.ts,
+ * revalidate-renderer.ts, wrap-action-dispatch.ts, ...). Don't add
+ * rendering or response-shaping logic here — extract it to a sibling.
+ *
  * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
  */
 
@@ -38,8 +46,6 @@ import globalSchemaCodecs from 'virtual:timber-schema';
 import { wrapPipelineWithActionDispatch } from './wrap-action-dispatch.js';
 import type { BodyLimitsConfig } from '../body-limits.js';
 import type { BuildManifest } from '../build-manifest.js';
-import type { LayoutEntry } from '../deny-renderer.js';
-import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
 import { resolveLogMode } from '../../dev-tools/logger.js';
 import { sendEarlyHints103 } from '../early-hints-sender.js';
 import { collectEarlyHintHeaders } from '../early-hints.js';
@@ -47,19 +53,15 @@ import { buildClientScripts } from '../html-injectors.js';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from '../pipeline.js';
 import { createPipeline } from '../pipeline.js';
 import { coerceSegmentParams, setGlobalSchemaCodecs } from '../param-coercion.js';
-import type { ManifestSegmentNode } from '../route-matcher.js';
 import { createMetadataRouteMatcher, createRouteMatcher } from '../route-matcher.js';
 import { initDevTracing } from '../tracing.js';
 import { createRevalidateRendererFactory } from './revalidate-renderer.js';
 
 import { renderFallbackError as renderFallback } from '../fallback-error.js';
 import { loadInstrumentation } from '../instrumentation.js';
-import { loadModule } from '../safe-load.js';
-import { logRenderError } from '../logger.js';
+import { createDenyFallbackRenderer } from './deny-fallback.js';
 import { renderNoMatchPage } from './error-renderer.js';
-import { createDebugChannelSink, isRscPayloadRequest } from './helpers.js';
 import { renderRoute } from './render-route.js';
-import { callSsr } from './ssr-bridge.js';
 import { isDebug, isDevMode, setDebugFromConfig } from '../debug.js';
 import { setSourceMapCallback } from '../dev-source-map.js';
 import { requestContextAls } from '../als-registry.js';
@@ -373,69 +375,13 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
         // set by the dev server after import, read at request time.
         isDev ? pipelineConfig.devHmrOptions : undefined
       ),
-    renderDenyFallback: async (deny, req, responseHeaders, matchedRoute) => {
-      // Render the deny page (403.tsx, 404.tsx, etc.) for DenySignals
-      // that escape from middleware or the render phase.
-      //
-      // When the pipeline already matched a route (the common case — matching
-      // runs before middleware and rendering), resolve the status file against
-      // the matched chain so colocated files like a nested `403.tsx` or an API
-      // route's `401.json` are picked up. Fall back to the root chain when no
-      // match is available (e.g. proxy-stage deny before route matching).
-      // See TIM-822, design/04-authorization.md, design/10-error-handling.md.
-      const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [manifest.root];
-      const layoutComponents: LayoutEntry[] = [];
-      try {
-        for (const segment of chain) {
-          if (!segment.layout) continue;
-          const mod = await loadModule(segment.layout);
-          if (mod.default) {
-            layoutComponents.push({
-              component: mod.default as (...args: unknown[]) => unknown,
-              segment,
-            });
-          }
-        }
-      } catch (layoutError) {
-        // Layout failed to load — proceed without it. Partial layout chains
-        // are acceptable; the deny renderer wraps in whatever loaded.
-        logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
-      }
-      // Reuse the matched route's params/middleware metadata when present so
-      // downstream rendering sees the real route shape. Otherwise synthesise
-      // a root-only stub (no params, no middleware).
-      const match: RouteMatch = matchedRoute ?? {
-        segments: chain,
-        segmentParams: {},
-        middlewareChain: [],
-      };
-      // For client navigation (Accept: text/x-component), the timber router
-      // decodes the response as React Flight. Returning HTML to a Flight
-      // decoder breaks navigation, so dispatch to the RSC renderer when the
-      // request is an RSC payload request — mirroring the normal render path.
-      // See design/19-client-navigation.md §"RSC Payload Handling" and TIM-823.
-      if (isRscPayloadRequest(req)) {
-        return renderDenyPageAsRsc(
-          deny,
-          chain,
-          layoutComponents,
-          req,
-          responseHeaders,
-          createDebugChannelSink
-        );
-      }
-      return renderDenyPage(
-        deny,
-        chain,
-        layoutComponents,
-        req,
-        match,
-        responseHeaders,
-        clientBootstrap,
-        createDebugChannelSink,
-        callSsr
-      );
-    },
+    // Deny fallback — renders the deny page (403.tsx, 404.tsx, etc.) for
+    // DenySignals that escape from middleware or the render phase.
+    // See deny-fallback.ts, design/04-authorization.md, design/10-error-handling.md.
+    renderDenyFallback: createDenyFallbackRenderer({
+      rootSegment: manifest.root,
+      clientBootstrap,
+    }),
     // Auto-generated sitemap handler — enabled when sitemap.enabled is true
     // and no user-authored sitemap exists at the app root.
     // See design/16-metadata.md §"Auto-generated Sitemap"

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

@@ -16,6 +16,51 @@
 
 import { swallow } from './logger.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;
+}
+
+// ─── State Tree Parsing ──────────────────────────────────────────
+
 /**
  * Parse the X-Timber-State-Tree header from a request.
  *
@@ -54,24 +99,24 @@ export function parseClientStateTree(req: Request): Set<string> | null {
  *
  * Additional constraints enforced by the caller (buildRouteElement):
  * - Must have a rendered layout below (so SegmentOutlet has content to show)
- * - Route groups are never skipped (siblings share urlPath)
+ * - Skipped segments must form a contiguous prefix from root
  *
  * Access.ts still runs for skipped segments — this is enforced by the caller
  * which wraps with AccessGate regardless of skip status.
  *
- * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
+ * @param segmentKey - The segment's state-tree key from computeSegmentKeys()
  * @param layoutComponent - The loaded layout component function
  * @param isLeaf - Whether this is the leaf segment (page segment)
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
 export function shouldSkipSegment(
-  urlPath: string,
+  segmentKey: string,
   layoutComponent: ((...args: unknown[]) => unknown) | undefined,
   isLeaf: boolean,
   clientSegments: Set<string> | null
 ): boolean {
   if (!clientSegments) return false;
-  if (!clientSegments.has(urlPath)) return false;
+  if (!clientSegments.has(segmentKey)) return false;
   if (!layoutComponent) return false;
   if (isLeaf) return false;