@timber-js/app 0.2.0-alpha.160 → 0.2.0-alpha.163

package/src/server/prebuilt-builder.ts

@@ -46,6 +46,7 @@ import { createElement } from 'react';
 
 import { requestContextAls } from './als-registry.js';
 import { ParamCoercionError } from './route-element-builder.js';
+import { ChildSegmentOutlet } from '../client/child-segment-outlet.js';
 import { coerceSegmentParams } from './param-coercion.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
 import {
@@ -154,6 +155,8 @@ interface CandidateRoute {
   layoutsToLoad: ManifestFile[];
   /** Component IDs attributed to this route's page + layout chain. */
   componentIds: string[];
+  /** Component IDs from layout files (receive ChildSegmentOutlet as children). */
+  layoutComponentIds: Set<string>;
 }
 
 /**
@@ -176,15 +179,20 @@ function collectCandidateRoutes(
 
     if (node.page) {
       const componentIds = new Set<string>();
-      for (const file of [...chain, node.page]) {
-        for (const id of fileComponentMap[file.filePath] ?? []) componentIds.add(id);
-      }
+      const layoutIds = new Set<string>();
+      for (const f of chain)
+        for (const id of fileComponentMap[f.filePath] ?? []) {
+          componentIds.add(id);
+          layoutIds.add(id);
+        }
+      for (const id of fileComponentMap[node.page.filePath] ?? []) componentIds.add(id);
       if (componentIds.size > 0) {
         routes.push({
           urlPath: node.urlPath,
           page: node.page,
           layoutsToLoad: chain.filter((l) => (fileComponentMap[l.filePath] ?? []).length > 0),
           componentIds: Array.from(componentIds),
+          layoutComponentIds: layoutIds,
         });
       }
     }
@@ -252,15 +260,14 @@ async function enumerateCombos(
 
 // ─── Rendering ────────────────────────────────────────────────────────────
 
-/** Concatenate drained chunks without Buffer (the bundle also runs on Workers). */
 function concatChunks(chunks: Uint8Array[]): Uint8Array {
   let total = 0;
-  for (const chunk of chunks) total += chunk.byteLength;
+  for (const c of chunks) total += c.byteLength;
   const out = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    out.set(chunk, offset);
-    offset += chunk.byteLength;
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.byteLength;
   }
   return out;
 }
@@ -299,10 +306,10 @@ async function drainWithTimeout(
 
 /** Wrap payload bytes as a single-chunk stream for the smoke revival. */
 function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
+  return new ReadableStream({
+    start(c) {
+      c.enqueue(bytes);
+      c.close();
     },
   });
 }
@@ -332,7 +339,8 @@ async function renderEntry(
   registration: PrebuiltRegistration,
   props: Record<string, unknown>,
   coercedParams: Record<string, string | string[]>,
-  timeoutMs: number
+  timeoutMs: number,
+  isLayout: boolean
 ): Promise<EntryOutcome> {
   const storeHandle = createBuildTimeStore(registration.id, coercedParams);
   const { store, violations } = storeHandle;
@@ -348,9 +356,15 @@ async function renderEntry(
     // synthetic store (segmentParams.get() inside the component).
     // Tag resolution also runs inside this scope so function-form tags
     // that read segment params see the synthetic store (codex P2 on PR #858).
+    // Layout captures get <ChildSegmentOutlet /> as children so the
+    // cached payload has a context-driven hole (design/45, TIM-1181).
+    const renderProps =
+      isLayout && !('children' in props)
+        ? { ...props, children: createElement(ChildSegmentOutlet as React.FC) }
+        : props;
     bytes = await requestContextAls.run(store, async () => {
       const stream = renderToReadableStream(
-        createElement(registration.component as RenderableComponent, props),
+        createElement(registration.component as RenderableComponent, renderProps),
         {
           onError(error: unknown) {
             failure ??= error ?? new Error('unknown render error');
@@ -422,7 +436,7 @@ function warnNestingClamps(
   let count = 0;
   for (const { innerId, options } of nested) {
     if (options.ttl === undefined && options.tags === undefined) continue;
-    const pairKey = `${outerId}${innerId}`;
+    const pairKey = `${outerId} ${innerId}`;
     if (warnedPairs.has(pairKey)) continue;
     warnedPairs.add(pairKey);
     count++;
@@ -448,6 +462,15 @@ function resolveCapturedTags(
   return resolved.length > 0 ? resolved : undefined;
 }
 
+/** Buffered entry pending the param-independence decision (TIM-1175). */
+interface PendingEntry {
+  callSiteProps: Record<string, unknown>;
+  cacheKey: string;
+  combo: ParamCombo;
+  bytes: Uint8Array;
+  tags: string[] | undefined;
+}
+
 /**
  * Capture flight payloads for every attributed, registered, prerender-tier
  * component across the route manifest. See module docblock for the flow.
@@ -465,9 +488,18 @@ export async function capturePrebuiltPayloads(
   const warnedPairs = new Set<string>();
   const reportedMissingRegistrations = new Set<string>();
   const eagerLoadedChunks = new Set<string>();
-  // Components confirmed to not read segmentParams during their first
-  // render — subsequent param combos reuse the first render's bytes.
-  const paramIndependentComponents = new Set<string>();
+  // Components already emitted as param-independent — skip on second route.
+  const emittedParamIndependent = new Set<string>();
+  // (componentId, propsKey) pairs that rendered at least once without
+  // reading segment params. Segment param access is structural (the
+  // component either calls getSegmentParams() or it doesn't), so if the
+  // first combo doesn't trigger it, subsequent combos won't either —
+  // skip them to avoid redundant renders. Tracked per props set so a
+  // failed variant doesn't suppress retries for a different variant.
+  const provenParamIndependent = new Set<string>();
+  // Per-component: whether ANY combo read segmentParams, plus buffered
+  // entries awaiting the param-independence decision after all combos.
+  const pendingByComponent = new Map<string, { anyParamRead: boolean; entries: PendingEntry[] }>();
 
   const skip = (issue: CaptureIssue) => {
     summary.skipped.push(issue);
@@ -594,8 +626,8 @@ export async function capturePrebuiltPayloads(
         }
         // Runtime tier (ttl/tags without prerender) does no build work.
         if (registration.options.prerender !== true) continue;
-        // Param-independent: first combo's renders cover all combos.
-        if (paramIndependentComponents.has(componentId)) continue;
+        // Already emitted as param-independent from a prior route.
+        if (emittedParamIndependent.has(componentId)) continue;
 
         // One entry per distinct call-site props object (design/44 §Props
         // Derivation, TIM-1142). When no call-site props were captured,
@@ -608,7 +640,23 @@ export async function capturePrebuiltPayloads(
         const propsSets: Record<string, unknown>[] =
           capturedProps && capturedProps.length > 0 ? [...capturedProps] : [{}];
 
+        let pending = pendingByComponent.get(componentId);
+        if (!pending) {
+          pending = { anyParamRead: false, entries: [] };
+          pendingByComponent.set(componentId, pending);
+        }
+
         for (const callSiteProps of propsSets) {
+          // Already rendered this (component, props) pair without reading
+          // params — additional combos produce identical payloads. Tracked
+          // per props set so a failed variant doesn't suppress retries.
+          // Guard on !anyParamRead: if another prop variant already proved
+          // param-dependent, this variant needs per-combo entries too since
+          // the emit phase uses a component-level paramIndependent flag.
+          const propsKey = JSON.stringify(callSiteProps);
+          const proofKey = `${componentId}\0${propsKey}`;
+          if (provenParamIndependent.has(proofKey) && !pending.anyParamRead) continue;
+
           const cacheKey = computeComponentCacheKey(callSiteProps, coercedParams);
           if (cacheKey === null) {
             skip({
@@ -621,11 +669,27 @@ export async function capturePrebuiltPayloads(
             });
             continue;
           }
-          const entryKey = `${componentId}${cacheKey}`;
+          const entryKey = `${componentId} ${cacheKey}`;
           if (seenEntries.has(entryKey)) continue;
           seenEntries.add(entryKey);
 
-          const outcome = await renderEntry(registration, callSiteProps, coercedParams, timeoutMs);
+          const isLayout = route.layoutComponentIds.has(componentId);
+          const outcome = await renderEntry(
+            registration,
+            callSiteProps,
+            coercedParams,
+            timeoutMs,
+            isLayout
+          );
+          // Track param reads immediately — before any failure continue —
+          // so a combo that reads params then fails still prevents
+          // param-independent classification (codex P1 on PR #869).
+          if (outcome.segmentParamsRead) {
+            pending.anyParamRead = true;
+            provenParamIndependent.delete(proofKey);
+          } else if (outcome.failure === null && !pending.anyParamRead) {
+            provenParamIndependent.add(proofKey);
+          }
           summary.nestingWarnings += warnNestingClamps(
             componentId,
             outcome.nested,
@@ -665,32 +729,46 @@ export async function capturePrebuiltPayloads(
             continue;
           }
 
-          // After the first successful render, if the component never
-          // read segmentParams, mark it param-independent — remaining
-          // combos reuse this render's bytes without re-rendering.
-          const isParamIndep = !outcome.segmentParamsRead;
-          if (isParamIndep) {
-            paramIndependentComponents.add(componentId);
-          }
-
-          const finalCacheKey = isParamIndep
-            ? (computeComponentCacheKey(callSiteProps, {}) ?? cacheKey)
-            : cacheKey;
-          const hasProps = Object.keys(callSiteProps).length > 0;
-          await options.onEntry({
-            componentId,
-            cacheKey: finalCacheKey,
-            params: isParamIndep ? {} : combo,
-            ...(hasProps ? { props: callSiteProps } : {}),
+          pending.entries.push({
+            callSiteProps,
+            cacheKey,
+            combo,
             bytes: outcome.bytes!,
             tags: outcome.resolvedTags,
-            ...(isParamIndep ? { paramIndependent: true } : {}),
           });
-          summary.captured++;
         }
       }
     }
   }
 
+  // Emit buffered entries. Param-independent = ALL combos rendered and
+  // NONE read segmentParams → collapse to one entry per props set (TIM-1175).
+  for (const [componentId, pending] of pendingByComponent) {
+    const isParamIndep = !pending.anyParamRead && pending.entries.length > 0;
+    if (isParamIndep) emittedParamIndependent.add(componentId);
+    const emittedProps = isParamIndep ? new Set<string>() : null;
+    for (const entry of pending.entries) {
+      if (emittedProps) {
+        const propsKey = JSON.stringify(entry.callSiteProps);
+        if (emittedProps.has(propsKey)) continue;
+        emittedProps.add(propsKey);
+      }
+      const hasProps = Object.keys(entry.callSiteProps).length > 0;
+      const finalCacheKey = isParamIndep
+        ? (computeComponentCacheKey(entry.callSiteProps, {}) ?? entry.cacheKey)
+        : entry.cacheKey;
+      await options.onEntry({
+        componentId,
+        cacheKey: finalCacheKey,
+        params: isParamIndep ? {} : entry.combo,
+        ...(hasProps ? { props: entry.callSiteProps } : {}),
+        bytes: entry.bytes,
+        tags: entry.tags,
+        ...(isParamIndep ? { paramIndependent: true } : {}),
+      });
+      summary.captured++;
+    }
+  }
+
   return summary;
 }

package/src/server/prebuilt-runtime.ts

@@ -37,6 +37,7 @@ import { createElement } from 'react';
 
 import { requestContextAls, type RequestContextStore } from './als-registry.js';
 import { computeComponentCacheKey, tryCanonicalize } from './prebuilt/cache-key.js';
+import { ChildSegmentOutlet } from '../client/child-segment-outlet.js';
 import {
   isCaptureActive,
   noteWrapperRender,
@@ -510,7 +511,29 @@ async function tryRevivePayload(
   const keyParams = paramIndep ? {} : resolveKeyParams(store);
   if (keyParams === null) return null;
 
-  const cacheKey = computeComponentCacheKey(props ?? {}, keyParams);
+  // Strip `children` from the cache key ONLY when it is the framework-
+  // injected ChildSegmentOutlet. Layout components receive
+  // <ChildSegmentOutlet /> as children — a deterministic client reference
+  // that is the same on every request, so it should not vary the key.
+  // User-provided React element children (e.g., <Cached><A /></Cached>)
+  // are NOT stripped — they remain unkeyable so the component renders
+  // live, which is correct: the cache cannot distinguish <A> from <B>.
+  // See design/45-cache-lifetimes.md §Layout Propagation, TIM-1181.
+  const allProps = (props ?? {}) as Record<string, unknown>;
+  let keyProps: Record<string, unknown>;
+  const childrenValue = allProps.children;
+  const isChildSegmentOutlet =
+    childrenValue != null &&
+    typeof childrenValue === 'object' &&
+    'type' in childrenValue &&
+    (childrenValue as { type: unknown }).type === ChildSegmentOutlet;
+  if (isChildSegmentOutlet) {
+    const { children: _children, ...rest } = allProps;
+    keyProps = rest;
+  } else {
+    keyProps = allProps;
+  }
+  const cacheKey = computeComponentCacheKey(keyProps, keyParams);
   if (cacheKey === null) return null;
 
   const outcome =

package/src/server/primitives.ts

@@ -416,11 +416,6 @@ export class RenderError<
 
 // ─── waitUntil ──────────────────────────────────────────────────────────────
 
-/** Minimal interface for adapters that support background work. */
-export interface WaitUntilAdapter {
-  waitUntil?(promise: Promise<unknown>): void;
-}
-
 // Intentional per-app singleton — warn-once flag that persists for the
 // lifetime of the process/isolate. Not per-request; do not migrate to ALS.
 let _waitUntilWarned = false;
@@ -429,30 +424,20 @@ let _waitUntilWarned = false;
  * Register a promise to be kept alive after the response is sent.
  * Maps to `ctx.waitUntil()` on Cloudflare Workers and similar platforms.
  *
- * In production, the platform adapter installs a per-request waitUntil
- * function via ALS (see waituntil-bridge.ts). This function checks the
- * ALS bridge first, then falls back to the legacy adapter argument.
- *
- * If neither is available, a warning is logged once and the promise is
- * left to resolve (or reject) without being tracked.
+ * The platform adapter installs a per-request waitUntil function via ALS
+ * (see waituntil-bridge.ts). If no ALS handler is available, a warning
+ * is logged once and the promise is left to resolve (or reject) without
+ * being tracked.
  *
  * @param promise - The background work to keep alive.
- * @param adapter - Optional legacy adapter (prefer ALS bridge in production).
  */
-export function waitUntil(promise: Promise<unknown>, adapter?: WaitUntilAdapter): void {
-  // Check ALS bridge first (installed by generated entry points)
+export function waitUntil(promise: Promise<unknown>): void {
   const alsFn = _getWaitUntil();
   if (alsFn) {
     alsFn(promise);
     return;
   }
 
-  // Fall back to legacy adapter argument
-  if (adapter && typeof adapter.waitUntil === 'function') {
-    adapter.waitUntil(promise);
-    return;
-  }
-
   if (!_waitUntilWarned) {
     _waitUntilWarned = true;
     console.warn(

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

@@ -44,10 +44,12 @@ import type { DenyPageEntry } from './deny-boundary.js';
 import { resolveSlotElement } from './slot-resolver.js';
 import { SegmentProvider } from '../client/segment-context.js';
 import { SegmentOutlet } from '../client/segment-outlet.js';
+import { ChildSegmentOutlet } from '../client/child-segment-outlet.js';
+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';
 
 /**
@@ -126,7 +128,7 @@ export function isClientReference(component: unknown): boolean {
   );
 }
 
-// ─── Param Coercion Error ─────────────────────────────────────────────────
+// ─── Typed Errors ────────────────────────────────────────────────────────
 
 /**
  * Thrown when a defineSegmentParams codec's parse() fails.
@@ -139,6 +141,17 @@ export class ParamCoercionError extends Error {
   }
 }
 
+/**
+ * Thrown when a matched route has no page component in its leaf segment.
+ * The pipeline catches this and renders the custom 404 page.
+ */
+export class NoPageComponentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NoPageComponentError';
+  }
+}
+
 // ─── Types ────────────────────────────────────────────────────────────────
 
 /** Layout entry with component and segment. */
@@ -352,7 +365,7 @@ export async function buildRouteElement(
           `  [${i}] ${s.segmentName} (page: ${s.page ? 'yes' : 'no'}, layout: ${s.layout ? 'yes' : 'no'}, children: ${s.children?.length ?? 0})${i === segments.length - 1 ? ' ← leaf' : ''}`
       )
       .join('\n');
-    throw new Error(
+    throw new NoPageComponentError(
       `No page component found for route: ${new URL(req.url).pathname}\nMatched segments:\n${segmentInfo}`
     );
   }
@@ -502,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
@@ -566,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,
@@ -583,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
@@ -641,22 +669,21 @@ 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.
-      // Same client reference guard as pages — client layouts must not be
-      // called as functions. OTEL tracing is skipped for client components.
+      // Layouts receive <ChildSegmentOutlet /> as children — a stable client
+      // reference — instead of the varying inner content. The actual child
+      // content is provided via ChildSegmentProvider above the layout.
+      // This makes layout cache.component hits possible: the cached payload
+      // contains a deterministic children reference, not varying content.
+      // See design/45-cache-lifetimes.md §Layout Propagation.
+      const childOutlet = h(ChildSegmentOutlet, {});
       let layoutElement: React.ReactElement;
       if (isClientReference(layoutComponent)) {
         layoutElement = h(layoutComponent, {
           ...slotProps,
-          children: element,
+          children: childOutlet,
         });
       } else {
         // Server component layout — wrap with OTEL tracing AND DenySignal
@@ -686,10 +713,17 @@ export async function buildRouteElement(
         };
         layoutElement = h(TracedLayout, {
           ...slotProps,
-          children: element,
+          children: childOutlet,
         });
       }
 
+      // Wrap the layout in ChildSegmentProvider so ChildSegmentOutlet
+      // (inside the layout's children) can read the actual child content.
+      layoutElement = h(ChildSegmentProvider, {
+        childContent: element,
+        children: layoutElement,
+      });
+
       const segmentProviderElement = h(SegmentProvider, {
         segments: segmentPath,
         segmentId,