@timber-js/app 0.2.0-alpha.171 → 0.2.0-alpha.173

package/src/client/segment-cache.ts

@@ -23,10 +23,20 @@ export interface SegmentNode {
   segment: string;
   /** The RSC flight payload for this segment (opaque to the cache) */
   payload: unknown;
-  /** Whether the segment is async (async layouts always re-render on navigation) */
-  isAsync: boolean;
+  /**
+   * Whether the segment/slot is request-dependent (calls getHeaders,
+   * getSearchParams, cookies, etc.). Request-dependent segments always
+   * re-render on navigation. For segments, this is still based on the
+   * AsyncFunction heuristic (to be replaced separately). For slots,
+   * this is taint-tracked via ALS.
+   */
+  isRequestDependent: boolean;
   /** Child segments keyed by segment path */
   children: Map<string, SegmentNode>;
+  /** Parallel route slots keyed by slot path (e.g., "/@sidebar") */
+  slots?: Map<string, SegmentNode>;
+  /** Whether this slot's access.ts denied on its last render. */
+  denied?: boolean;
 }
 
 /**
@@ -35,6 +45,7 @@ export interface SegmentNode {
  */
 export interface StateTree {
   segments: string[];
+  slots?: string[];
 }
 
 // ─── Segment Cache ───────────────────────────────────────────────
@@ -79,10 +90,16 @@ export class SegmentCache {
    */
   serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
+    const slots: string[] = [];
     if (this.root) {
       collectSyncSegments(this.root, segments, mergeableFilter);
+      collectSyncSlots(this.root, slots);
+    }
+    const tree: StateTree = { segments };
+    if (slots.length > 0) {
+      tree.slots = slots;
     }
-    return { segments };
+    return tree;
   }
 }
 
@@ -92,7 +109,7 @@ function collectSyncSegments(
   out: string[],
   mergeableFilter?: Set<string>
 ): void {
-  if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) {
+  if (!node.isRequestDependent && (!mergeableFilter || mergeableFilter.has(node.segment))) {
     out.push(node.segment);
   }
   for (const child of node.children.values()) {
@@ -100,6 +117,22 @@ function collectSyncSegments(
   }
 }
 
+/** Recursively collect cacheable slot paths from the tree */
+function collectSyncSlots(node: SegmentNode, out: string[]): void {
+  if (node.slots) {
+    for (const slot of node.slots.values()) {
+      // Exclude request-dependent slots (they must re-render every nav)
+      // and denied slots (their cached content is denial fallback, not real content)
+      if (!slot.isRequestDependent && !slot.denied) {
+        out.push(slot.segment);
+      }
+    }
+  }
+  for (const child of node.children.values()) {
+    collectSyncSlots(child, out);
+  }
+}
+
 // ─── Segment Tree Builder ────────────────────────────────────────
 
 /**
@@ -110,7 +143,13 @@ export interface SegmentInfo {
   path: string;
   /** Outlet key — includes route group name when applicable (e.g., "/(marketing)"). */
   segmentId?: string;
-  isAsync: boolean;
+  isRequestDependent: boolean;
+  /** True for parallel route slot entries. Slots are keyed by their slot path (e.g., "/@sidebar"). */
+  slot?: boolean;
+  /** Parent segment path for slot entries. Used to attach the slot to the correct SegmentNode. */
+  parentSegment?: string;
+  /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
+  denied?: boolean;
 }
 
 /**
@@ -128,21 +167,34 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
   // Need at least a root segment to build a tree
   if (segments.length === 0) return undefined;
 
-  // All entries are layout segments — the server filters out layoutless
-  // segments (including the page leaf) in buildSegmentInfo. Cache every
-  // entry; pages are never sent.
+  // Separate slot entries from segment entries. Slots are attached to
+  // their parent segment node after the main chain is built.
+  const segmentEntries: SegmentInfo[] = [];
+  const slotEntries: SegmentInfo[] = [];
+  for (const info of segments) {
+    if (info.slot) {
+      slotEntries.push(info);
+    } else {
+      segmentEntries.push(info);
+    }
+  }
+
+  // Build the main segment chain.
   let root: SegmentNode | undefined;
   let parent: SegmentNode | undefined;
+  const nodeById = new Map<string, SegmentNode>();
 
-  for (const info of segments) {
+  for (const info of segmentEntries) {
     const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
       segment: id,
       payload: null,
-      isAsync: info.isAsync,
+      isRequestDependent: info.isRequestDependent,
       children: new Map(),
     };
 
+    nodeById.set(id, node);
+
     if (!root) {
       root = node;
     }
@@ -154,6 +206,27 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
     parent = node;
   }
 
+  // Attach slot entries to their parent segment nodes.
+  for (const slotInfo of slotEntries) {
+    const parentId = slotInfo.parentSegment;
+    const parentNode = parentId ? nodeById.get(parentId) : root;
+    if (!parentNode) continue;
+
+    const slotId = slotInfo.segmentId ?? slotInfo.path;
+    const slotNode: SegmentNode = {
+      segment: slotId,
+      payload: null,
+      isRequestDependent: slotInfo.isRequestDependent,
+      children: new Map(),
+      denied: slotInfo.denied,
+    };
+
+    if (!parentNode.slots) {
+      parentNode.slots = new Map();
+    }
+    parentNode.slots.set(slotId, slotNode);
+  }
+
   return root;
 }
 

package/src/client/segment-outlet.tsx

@@ -32,12 +32,21 @@ export interface SegmentOutletProps {
    * Unique identifier for this segment. For normal segments this is the
    * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
    * group name (e.g., "/(marketing)") to distinguish siblings that share
-   * the same urlPath. Must match the segmentId used in state-tree-diff.ts.
+   * the same urlPath. For slots this includes the slot name (e.g., "/@sidebar").
+   * Must match the segmentId used in state-tree-diff.ts.
    */
   segmentPath: string;
 
   /** The segment's React subtree (layout + inner content). */
   children: ReactNode;
+
+  /**
+   * When true, the outlet returns cached content instead of rendering
+   * new children. Used for skipped parallel route slots — the server
+   * sends an empty SegmentOutlet with skip=true, and the client keeps
+   * the previously cached slot content.
+   */
+  skip?: boolean;
 }
 
 /**
@@ -52,7 +61,7 @@ export interface SegmentOutletProps {
  * when the same type appears at the same tree position. The ref persists
  * across navigations because SegmentOutlet is reconciled, not remounted.
  */
-export function SegmentOutlet({ segmentPath, children }: SegmentOutletProps) {
+export function SegmentOutlet({ segmentPath, children, skip }: SegmentOutletProps) {
   const updates = useContext(SegmentUpdateContext);
   const contentRef = useRef<ReactNode>(null);
 
@@ -63,6 +72,19 @@ export function SegmentOutlet({ segmentPath, children }: SegmentOutletProps) {
     return update;
   }
 
+  // Skipped slot: keep cached content. The server sends skip=true for
+  // parallel route slots whose matched content hasn't changed. React
+  // reconciles this SegmentOutlet with the previous one at the same
+  // tree position, so the ref (cached content) is preserved.
+  if (skip) {
+    if (contentRef.current !== null) {
+      return contentRef.current;
+    }
+    // No cached content — the SegmentOutlet instance is fresh (not
+    // reconciled from a previous render). Fall through to render
+    // children (null). The slot will be fully rendered next navigation.
+  }
+
   if (contentRef.current === null) {
     contentRef.current = children;
     return children;

package/src/client/slot-context.ts

@@ -8,18 +8,20 @@
  * SlotsProvider carrying the live slot values; each outlet reads its
  * value from this context by name.
  *
- * The value is a per-instance record — the NEAREST provider wins, so two
- * instances of the same cached component on one page each resolve their
- * own children, and a slot component nested inside another slot
- * component's children reads its own provider, not the outer one.
+ * Providers MERGE per-key with their parent: an inner SlotsProvider
+ * inherits the outer's values and overrides only the keys it declares.
+ * Two sibling instances each have their own provider and resolve
+ * independently. Layouts use a reserved slot name (LAYOUT_CHILDREN_SLOT)
+ * that cannot collide with user-declared slot names (TIM-1191).
  *
- * Generalizes the ChildSegmentContext pattern (TIM-1181) from a single
- * implicit `children` hole on layouts to explicitly declared, named slot
- * props on any cached component.
+ * Generalizes the original layout children pattern (TIM-1181) from a
+ * single implicit `children` hole on layouts to explicitly declared,
+ * named slot props on any cached component. Layouts use this same
+ * context with the reserved LAYOUT_CHILDREN_SLOT key (TIM-1191).
  *
  * SINGLETON GUARANTEE: globalThis + Symbol.for — the RSC client bundler
  * can duplicate this module across chunks; globalThis guarantees a single
- * context instance. Same pattern as ChildSegmentContext.
+ * context instance.
  *
  * See design/45-cache-lifetimes.md §Slot Components.
  */

package/src/client/slot-provider.tsx

@@ -2,6 +2,11 @@
  * SlotsProvider — wraps a revived cached shell to supply live slot content
  * to the SlotOutlet holes inside it (TIM-1173).
  *
+ * Values MERGE with the nearest parent provider so that nesting a
+ * cache.component SlotsProvider inside a layout SlotsProvider preserves
+ * the layout's `children` slot while adding the component's own slots.
+ * Inner values override outer ones with the same name (spread order).
+ *
  * Tree structure per cached-component instance:
  *   SlotsProvider(values={children: <Live />})
  *     └── revived shell
@@ -12,7 +17,7 @@
 
 'use client';
 
-import { createElement, type ReactNode } from 'react';
+import { createElement, useContext, type ReactNode } from 'react';
 import { SlotContext, type SlotValues } from './slot-context.js';
 
 interface SlotsProviderProps {
@@ -21,5 +26,7 @@ interface SlotsProviderProps {
 }
 
 export function SlotsProvider({ values, children }: SlotsProviderProps) {
-  return createElement(SlotContext.Provider, { value: values }, children);
+  const parent = useContext(SlotContext);
+  const merged = parent ? { ...parent, ...values } : values;
+  return createElement(SlotContext.Provider, { value: merged }, children);
 }

package/src/server/access-gate.tsx

@@ -124,8 +124,35 @@ async function accessGateFallback(
  * slot doesn't make architectural sense.
  */
 export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactNode> {
-  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children, verdict } =
+    props;
 
+  // Fast path: replay pre-computed verdict from eager evaluation in resolveSlotProps.
+  if (verdict !== undefined) {
+    if (verdict === 'pass') return children;
+    if (verdict instanceof DenySignal) {
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, verdict.data, createElement) ??
+        defaultFallback ??
+        null
+      );
+    }
+    // RedirectSignal: treat as deny in production (same as existing behavior)
+    if (isDebug()) {
+      console.error(
+        '[timber] redirect() is not allowed in slot access.ts. ' +
+          'Slots use deny() for graceful degradation — denied.tsx → default.tsx → null. ' +
+          "If you need to redirect, move the logic to the parent segment's access.ts."
+      );
+    }
+    return (
+      buildDeniedFallback(DeniedComponent, slotName, undefined, createElement) ??
+      defaultFallback ??
+      null
+    );
+  }
+
+  // Fallback path: call accessFn during render (no pre-computed verdict).
   try {
     await accessFn();
   } catch (error: unknown) {

package/src/server/als-registry.ts

@@ -140,6 +140,18 @@ export interface RequestContextStore {
    * context for render-phase errors without module-level shared state.
    */
   debugComponentsGetter?: () => DebugComponentEntry[];
+  /**
+   * Taint tracking results from render-time accessor scope tracking.
+   * Keyed by segment/slot ID, true = accessor was called during render.
+   * Populated by runInTaintScope() wrappers in TracedLayout and slot
+   * resolution; consumed by buildSegmentInfo() for X-Timber-Segments.
+   */
+  taintResults?: Map<string, boolean>;
+  /**
+   * Set to true if an accessor is called outside any taint scope.
+   * When true, all segments are marked request-dependent (safe fallback).
+   */
+  orphanTaint?: boolean;
 }
 
 /** A single outgoing cookie entry in the cookie jar. */
@@ -149,6 +161,38 @@ export interface CookieEntry {
   options: import('./cookie-context.js').CookieOptions;
 }
 
+// ─── Taint Scope ─────────────────────────────────────────────────────────
+// Per-component accessor taint tracking. Each scope runs inside its own
+// ALS context so concurrent async components (Flight renders siblings in
+// parallel) don't corrupt each other's touched flags.
+
+export interface TaintScope {
+  touched: boolean;
+}
+
+export const taintScopeAls = getOrCreateAls<TaintScope>(Symbol.for('timber:taint-scope-als'));
+
+/**
+ * Mark that a request accessor was called in the current scope.
+ * If a taint scope is active, marks that scope. If no scope is active
+ * but a request context exists, sets the orphan taint flag (all segments
+ * become request-dependent as a safety fallback).
+ *
+ * Lives here (not request-context.ts) to avoid circular deps with
+ * cookie-context.ts which also needs to call it.
+ */
+export function markAccessorTouched(): void {
+  const scope = taintScopeAls.getStore();
+  if (scope) {
+    scope.touched = true;
+    return;
+  }
+  const store = requestContextAls.getStore();
+  if (store) {
+    store.orphanTaint = true;
+  }
+}
+
 // ─── Tracing ──────────────────────────────────────────────────────────────
 // Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md

package/src/server/cookie-context.ts

@@ -12,7 +12,11 @@
  * smuggling primitive that the encoding contract closes.
  */
 
-import { requestContextAls, type RequestContextStore } from './als-registry.js';
+import {
+  requestContextAls,
+  markAccessorTouched,
+  type RequestContextStore,
+} from './als-registry.js';
 import { isDebug } from './debug.js';
 import {
   assertValidCookieName,
@@ -62,6 +66,8 @@ export function getCookieJar(): RequestCookies {
     );
   }
 
+  markAccessorTouched();
+
   // Parse cookies lazily on first access
   if (!store.parsedCookies) {
     store.parsedCookies = parseCookieHeader(store.cookieHeader);

package/src/server/deny-renderer.ts

@@ -26,7 +26,7 @@ import { loadModule } from './safe-load.js';
 import { isMdxFilePath } from './utils/mdx-file.js';
 import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import { headElementsToReact } from './route-element-builder.js';
+import { headElementsToReact } from './metadata.js';
 import { resolveStatusFile } from './status-code-resolver.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';

package/src/server/metadata-routes.ts

@@ -10,6 +10,11 @@
  * See design/16-metadata.md §"Metadata Routes"
  */
 
+import { randomUUID } from 'node:crypto';
+import type { HeadElement } from './metadata.js';
+import type { Metadata } from './types.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 /** Classification of a metadata route file. */
@@ -334,3 +339,93 @@ export function getMetadataRouteAutoLink(type: MetadataRouteType, href: string):
       return [];
   }
 }
+
+// ─── Auto-Linking ──────────────────────────────────────────────────────────
+
+// In dev mode, use a per-startup nonce for metadata route cache busting
+// instead of per-file content hashes (avoids rehashing on every request).
+let _devNonce: string | undefined;
+function getDevNonce(): string {
+  _devNonce ??= randomUUID().slice(0, 8);
+  return _devNonce;
+}
+
+/**
+ * Collect auto-linked head elements from metadata route files in the segment chain.
+ *
+ * Walks each segment's metadataRoutes, resolves serve paths and URLs, and
+ * emits HeadElement descriptors for <link> and <meta> tags that React Float
+ * hoists into <head>.
+ *
+ * See design/16-metadata.md §"Auto-Linking"
+ */
+export function collectMetadataRouteHeadElements(
+  segments: ManifestSegmentNode[],
+  firstDeniedIndex: number,
+  resolvedMetadata: Metadata,
+  requestUrl: URL,
+  metadataRouteHashes?: Record<string, string>
+): HeadElement[] {
+  const elements: HeadElement[] = [];
+  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);
+  const hasUserTwitterImage = Boolean(resolvedMetadata.twitter?.images);
+  const requestPathname = requestUrl.pathname;
+  // In dev mode, use the request origin so OG URLs resolve to localhost.
+  // In production, use metadataBase (the canonical domain).
+  const ogBase =
+    process.env.NODE_ENV !== 'production'
+      ? new URL(requestUrl.origin)
+      : resolvedMetadata.metadataBase;
+
+  for (let si = 0; si < segments.length; si++) {
+    const segment = segments[si];
+    if (!segment.metadataRoutes) continue;
+    if (si >= firstDeniedIndex) continue;
+    for (const baseName of Object.keys(segment.metadataRoutes)) {
+      const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+      if (!convention) continue;
+      if (!convention.nestable && segment.urlPath !== '/') continue;
+      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;
+      const resolvedPrefix = convention.nestable
+        ? requestPathname === '/'
+          ? ''
+          : requestPathname
+        : '';
+      const metaFile = segment.metadataRoutes[baseName];
+      const fileServePath = metaFile?.filePath
+        ? resolveServePathForFile(baseName, metaFile.filePath)
+        : convention.serveExtension
+          ? `${convention.servePath}.${convention.serveExtension}`
+          : convention.servePath;
+      let href = `${resolvedPrefix}/${fileServePath}`;
+      if (convention.type === 'opengraph-image') {
+        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;
+        const cacheBust = fileHash ?? getDevNonce();
+        href = `${href}?${cacheBust}`;
+      }
+      if (ogBase && convention.type === 'opengraph-image') {
+        href = new URL(href, ogBase).toString();
+      }
+      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {
+        if (
+          hasUserTwitterImage &&
+          autoLink.tag === 'meta' &&
+          'name' in autoLink &&
+          autoLink.name === 'twitter:image'
+        )
+          continue;
+        if (autoLink.tag === 'link') {
+          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
+          if (autoLink.type) attrs.type = autoLink.type;
+          elements.push({ tag: 'link', attrs });
+        } else {
+          const attrs: Record<string, string> = { content: autoLink.content };
+          if (autoLink.property) attrs.property = autoLink.property;
+          if (autoLink.name) attrs.name = autoLink.name;
+          elements.push({ tag: 'meta', attrs });
+        }
+      }
+    }
+  }
+  return elements;
+}

package/src/server/metadata.ts

@@ -12,12 +12,33 @@
  * See design/16-metadata.md
  */
 
+import { createElement, Fragment } from 'react';
 import type { Metadata } from './types.js';
 
 // Re-export renderMetadataToElements from the rendering module so existing
 // consumers (route-element-builder, tests) can keep importing from here.
 export { renderMetadataToElements } from './metadata-render.js';
 
+/**
+ * Convert HeadElement descriptors to React elements for Float hoisting.
+ *
+ * React 19 Float hoists <title>, <meta>, and <link> rendered anywhere in
+ * the tree into <head> during SSR, and manages them in document.head
+ * during client-side rendering.
+ */
+export function headElementsToReact(elements: HeadElement[]): React.ReactElement {
+  const children: React.ReactElement[] = [];
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (el.tag === 'title' && el.content !== undefined) {
+      children.push(createElement('title', { key: `t${i}` }, el.content));
+    } else if (el.attrs) {
+      children.push(createElement(el.tag, { key: `h${i}`, ...el.attrs }));
+    }
+  }
+  return createElement(Fragment, null, ...children);
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 /** A single metadata entry from a layout or page module. */

package/src/server/prebuilt/slots.ts

@@ -5,8 +5,8 @@
  * as a shell with a stable <SlotOutlet slot={name} /> client-reference
  * hole per declared slot prop; live slot content composes in per instance
  * at request time via SlotsProvider/SlotContext. This generalizes the
- * TIM-1181 layout mechanism (ChildSegmentOutlet) to explicitly declared,
- * named slots on any cached component.
+ * TIM-1181 layout mechanism to explicitly declared, named slots on any
+ * cached component. Layouts use the same mechanism with a `children` slot.
  *
  * Both the production wrapper (cache path) and the dev wrapper (no cache,
  * same tree shape for dev/prod parity) build their render from these
@@ -16,27 +16,50 @@
 import { createElement } from 'react';
 
 import type { SlotValues } from '../../client/slot-context.js';
-import { ChildSegmentOutlet } from '../../client/child-segment-outlet.js';
 import { SlotOutlet } from '../../client/slot-outlet.js';
 import { SlotsProvider } from '../../client/slot-provider.js';
 import { splitSlotProps } from './cache-key.js';
 import type { PrebuiltComponentOptions } from '../prebuilt-runtime.js';
 
 /**
- * Is this value the framework-injected `<ChildSegmentOutlet />` element?
- * Total: the `in` probe and `.type` read run against a user-controlled
- * value, and a Proxy trap can throw — that must classify as "not the
- * outlet" (the canonicalizer then rejects the value as unkeyable → live
- * render), not abort the request (codex P2 on PR #890).
+ * Framework-internal slot name for layout children. Uses a prefix that
+ * cannot collide with user-declared slot names (which are React prop
+ * names). Layout children flow through SlotsProvider/SlotOutlet with
+ * this key instead of the bare "children" key, so a cached component
+ * with `slots: ['children']` inside a layout never shadows the layout's
+ * own children delivery.
+ *
+ * Defined here (a server module) rather than in `client/slot-context.ts`
+ * (`'use client'`) because RSC's client-reference proxying would replace
+ * the string value with a proxy object in the server environment. The
+ * client-side SlotOutlet receives this value via props, so it doesn't
+ * need the constant. See TIM-1191.
  */
-export function isChildSegmentOutletElement(value: unknown): boolean {
+export const LAYOUT_CHILDREN_SLOT = '\0timber:children';
+
+/**
+ * Is this value the framework-injected layout children slot outlet
+ * (`<SlotOutlet slot={LAYOUT_CHILDREN_SLOT} />`)? Layout components
+ * receive this as their `children` prop — a stable client reference
+ * whose cache key is stripped so layout `cache.component` hits work
+ * (design/45 §Layout Propagation).
+ *
+ * Uses a framework-reserved slot name (LAYOUT_CHILDREN_SLOT) that
+ * cannot collide with user-declared slot names, preventing context
+ * shadowing when a cached component with its own SlotsProvider is
+ * nested inside a layout. See TIM-1191.
+ *
+ * Total: the probes run against a user-controlled value, and a Proxy
+ * trap can throw — that must classify as "not the outlet" (the
+ * canonicalizer then rejects the value as unkeyable → live render), not
+ * abort the request (codex P2 on PR #890).
+ */
+export function isChildrenSlotOutletElement(value: unknown): boolean {
   try {
-    return (
-      value != null &&
-      typeof value === 'object' &&
-      'type' in value &&
-      (value as { type: unknown }).type === ChildSegmentOutlet
-    );
+    if (value == null || typeof value !== 'object') return false;
+    if (!('type' in value)) return false;
+    const el = value as { type: unknown; props?: { slot?: unknown } };
+    return el.type === SlotOutlet && el.props?.slot === LAYOUT_CHILDREN_SLOT;
   } catch {
     return false;
   }
@@ -161,7 +184,7 @@ export function wrapInSlotsProvider(
 ): React.ReactElement {
   // children passed as a prop, not a JSX child — the shell is `unknown`
   // to the type system. Same pattern as route-element-builder's `h` alias
-  // for ChildSegmentProvider.
+  // for SlotsProvider.
   const h = createElement as (...args: unknown[]) => React.ReactElement;
   return h(SlotsProvider, { values: slotValues as SlotValues, children: shell });
 }

package/src/server/prebuilt-builder.ts

@@ -46,7 +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 { SlotOutlet } from '../client/slot-outlet.js';
 import { coerceSegmentParams } from './param-coercion.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
 import {
@@ -56,6 +56,7 @@ import {
   type NestedWrapperRender,
 } from './prebuilt/capture-state.js';
 import { computeComponentCacheKey } from './prebuilt/cache-key.js';
+import { LAYOUT_CHILDREN_SLOT } from './prebuilt/slots.js';
 import { BuildTimeContextError, createBuildTimeStore } from './prebuilt/synthetic-store.js';
 import {
   getPrebuiltRegistration,
@@ -155,7 +156,7 @@ 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). */
+  /** Component IDs from layout files (receive SlotOutlet as children). */
   layoutComponentIds: Set<string>;
 }
 
@@ -356,11 +357,11 @@ 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).
+    // Layout captures get <SlotOutlet slot="children" /> 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, children: createElement(SlotOutlet, { slot: LAYOUT_CHILDREN_SLOT }) }
         : props;
     bytes = await requestContextAls.run(store, async () => {
       const stream = renderToReadableStream(