@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/src/client/segment-cache.ts

@@ -1,20 +1,39 @@
 // Segment Cache — stores the mounted segment tree and prefetched payloads
 // See design/19-client-navigation.md for architecture details.
 
-import type { HeadElement } from './head';
+import type { PublishedParams } from '../shared/payload-root.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
-/** A prefetched RSC result with optional head elements and segment metadata. */
+/** A prefetched RSC result with optional segment metadata. */
 export interface PrefetchResult {
   payload: unknown;
-  headElements: HeadElement[] | null;
+  /**
+   * Completion of the full Flight stream, when the prefetch is still decoding.
+   * Carried through to the navigation that consumes the entry so a decode
+   * failure reaches *that* navigation's recovery rather than dying with the
+   * prefetch (TIM-1275).
+   */
+  decodePromise?: Promise<void> | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo?: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
-  params?: Record<string, string | string[]> | null;
+  /**
+   * The params published beside `payload`, split off the same payload root.
+   * Carried so a consumed prefetch publishes the params of the tree it is
+   * about to render, and not the ones already on screen.
+   */
+  params?: PublishedParams | Promise<PublishedParams>;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;
+  /**
+   * HTTP status of the prefetched response. A deny payload is an ordinary
+   * Flight response carrying a 4xx, so it prefetches and caches like any
+   * other — and the tree it renders is one the segment cache must not learn
+   * from. Absent on entries that predate the field, and on the negative
+   * sentinel. See TIM-1356.
+   */
+  status?: number;
 }
 
 /**
@@ -24,20 +43,33 @@ export interface PrefetchResult {
 export interface SegmentNode {
   /** The segment's URL pattern (e.g., "/", "/dashboard", "/projects/[id]") */
   segment: string;
+  /**
+   * The segment's `app/` directory path, groups included (e.g. `/(browse)/feed`).
+   * Undefined for slot nodes and for servers that predate the field.
+   */
+  treePath?: 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>;
-}
-
-/**
- * Serialized state tree sent via X-Timber-State-Tree header.
- * Only sync segments are included — async segments always re-render.
- */
-export interface StateTree {
-  segments: string[];
+  /** 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;
+  /**
+   * Content key for slot nodes — opaque string the server computed from
+   * owner parts, slot name, entry file, and slot params. Advertised back
+   * to the server so it can decide skips by key membership (TIM-1370).
+   */
+  contentKey?: string;
 }
 
 // ─── Segment Cache ───────────────────────────────────────────────
@@ -77,15 +109,33 @@ export class SegmentCache {
    * client can actually merge (i.e., segments whose cached element tree
    * contains an inner SegmentProvider the merger can splice into).
    *
+   * `treePaths` is collected UNFILTERED, unlike `segments` and `slots`. Those
+   * two answer "what may the server skip re-rendering?", so every reason a
+   * segment cannot be reused is a reason to leave it out. `treePaths` answers
+   * "what is mounted right now?" for interception scoping — a request-dependent
+   * layout is still on screen, and dropping it would silently narrow the scope
+   * the server sees and cancel a modal that should open (TIM-1282).
+   *
    * This is a performance optimization only, NOT a security boundary.
    * The server always runs all access.ts files regardless of the state tree.
    */
   serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
+    const slots: string[] = [];
+    const treePaths: string[] = [];
     if (this.root) {
       collectSyncSegments(this.root, segments, mergeableFilter);
+      collectSyncSlots(this.root, slots);
+      collectTreePaths(this.root, treePaths);
+    }
+    const tree: StateTree = { segments };
+    if (slots.length > 0) {
+      tree.slots = slots;
     }
-    return { segments };
+    if (treePaths.length > 0) {
+      tree.treePaths = treePaths;
+    }
+    return tree;
   }
 }
 
@@ -95,7 +145,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()) {
@@ -103,17 +153,44 @@ function collectSyncSegments(
   }
 }
 
-// ─── Segment Tree Builder ────────────────────────────────────────
+/**
+ * Recursively collect the `app/` directory path of every mounted segment.
+ *
+ * Slots are not walked: a slot's own sub-tree can never own an intercepting
+ * slot's scope, because scopes are always ordinary segments (`interception.ts`
+ * derives one from the slot owner's ancestor chain).
+ */
+function collectTreePaths(node: SegmentNode, out: string[]): void {
+  if (node.treePath) out.push(node.treePath);
+  for (const child of node.children.values()) {
+    collectTreePaths(child, out);
+  }
+}
 
 /**
- * Segment metadata from the server, sent via X-Timber-Segments header.
- * Describes a rendered segment's path and whether it's async.
+ * Recursively collect content keys from cacheable slots.
+ *
+ * The server advertises a content key per slot on every render (TIM-1370),
+ * encoding the owner's URL parts, the slot name, the matched entry file,
+ * and the slot's params. The client stores this key and sends it back on
+ * the next navigation so the server can decide skips by key membership —
+ * no departing URL reconstruction needed.
  */
-export interface SegmentInfo {
-  path: string;
-  isAsync: boolean;
+function collectSyncSlots(node: SegmentNode, out: string[]): void {
+  if (node.slots) {
+    for (const slot of node.slots.values()) {
+      if (!slot.isRequestDependent && !slot.denied && slot.contentKey) {
+        out.push(slot.contentKey);
+      }
+    }
+  }
+  for (const child of node.children.values()) {
+    collectSyncSlots(child, out);
+  }
 }
 
+// ─── Segment Tree Builder ────────────────────────────────────────
+
 /**
  * Build a SegmentNode tree from flat segment metadata.
  *
@@ -129,32 +206,68 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
   // Need at least a root segment to build a tree
   if (segments.length === 0) return undefined;
 
-  // Exclude the leaf (page) — pages always re-render on navigation.
-  // Only layouts are cached in the segment tree.
-  const layouts = segments.length > 1 ? segments.slice(0, -1) : segments;
+  // 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 layouts) {
+  for (const info of segmentEntries) {
+    const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
-      segment: info.path,
+      segment: id,
+      treePath: info.treePath,
       payload: null,
-      isAsync: info.isAsync,
+      isRequestDependent: info.isRequestDependent,
       children: new Map(),
     };
 
+    nodeById.set(id, node);
+
     if (!root) {
       root = node;
     }
 
     if (parent) {
-      parent.children.set(info.path, node);
+      parent.children.set(id, node);
     }
 
     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,
+      contentKey: slotInfo.contentKey,
+    };
+
+    if (!parentNode.slots) {
+      parentNode.slots = new Map();
+    }
+    parentNode.slots.set(slotId, slotNode);
+  }
+
   return root;
 }
 
@@ -165,6 +278,61 @@ interface PrefetchEntry {
   expiresAt: number;
 }
 
+/** Sentinel value for negative cache entries (URL is not a route). */
+const NEGATIVE_ENTRY: PrefetchResult = Object.freeze({ payload: null });
+
+/**
+ * Identifies a prefetched payload. A payload is addressed by *every* input that
+ * changes the server's answer, not by the destination alone.
+ *
+ * The server's answer for a destination depends on where the request came
+ * from — that is the whole mechanism behind intercepting routes, and it also
+ * drives slot-skip resolution. A prefetch issued from `/gallery` is a modal
+ * payload; the same URL prefetched from `/` is the full page. Keying on the
+ * destination alone let the first click after a hover be answered with
+ * whichever variant happened to be fetched (TIM-1265).
+ *
+ * `from` alone stopped being enough in TIM-1282. It is a pathname, and once
+ * interception scope comes from the rendered tree rather than the address, one
+ * pathname no longer names one source tree: `/photo/1` is the address both for
+ * a modal open over `(browse)` and for `(landing)`'s canonical page. A key
+ * without the scope hands the modal payload to the canonical page's click,
+ * which renders it without the server's scope check ever running.
+ *
+ * The two reads happen at different instants — `scope` is sampled at hover and
+ * again at click — which is why a tree that changed in between produces a
+ * *miss* and a refetch rather than a wrong hit.
+ */
+export interface PrefetchKey {
+  /** Destination URL — hash-less `pathname + search`, as navigate() fetches it. */
+  url: string;
+  /** Departing pathname — the `X-Timber-URL` the prefetch was issued with. */
+  from: string;
+  /**
+   * The rendered scope the prefetch was issued with — the `treePaths` half of
+   * `X-Timber-State-Tree`, joined. Empty when none crossed.
+   */
+  scope: string;
+}
+
+/**
+ * Compose the map key. Length-prefixed rather than delimiter-joined for the
+ * same reason `shared/rsc-cache-key.ts` is: any delimiter is forgeable by a
+ * value containing it, and a URL may contain any character a delimiter could.
+ */
+function prefetchMapKey(key: PrefetchKey): string {
+  return `${key.from.length}:${key.from}:${key.scope.length}:${key.scope}:${key.url}`;
+}
+
+/**
+ * The `scope` half of a `PrefetchKey`, derived from the state tree that will
+ * actually be sent. Taking it from the header value rather than re-walking the
+ * cache is the point: the key varies by exactly what the request varies by.
+ */
+export function prefetchScopeOf(stateTree: StateTree | undefined): string {
+  return stateTree?.treePaths?.join('\u0000') ?? '';
+}
+
 /**
  * Short-lived cache for hover-triggered prefetches. Entries expire after
  * 30 seconds. When a link is clicked, the prefetched payload is consumed
@@ -177,29 +345,47 @@ export class PrefetchCache {
   private static readonly TTL_MS = 30_000;
   private entries = new Map<string, PrefetchEntry>();
 
-  set(url: string, result: PrefetchResult): void {
-    this.entries.set(url, {
+  set(key: PrefetchKey, result: PrefetchResult): void {
+    this.entries.set(prefetchMapKey(key), {
       result,
       expiresAt: Date.now() + PrefetchCache.TTL_MS,
     });
   }
 
-  get(url: string): PrefetchResult | undefined {
-    const entry = this.entries.get(url);
+  get(key: PrefetchKey): PrefetchResult | undefined {
+    const mapKey = prefetchMapKey(key);
+    const entry = this.entries.get(mapKey);
     if (!entry) return undefined;
     if (Date.now() >= entry.expiresAt) {
-      this.entries.delete(url);
+      this.entries.delete(mapKey);
       return undefined;
     }
     return entry.result;
   }
 
   /** Get and remove the entry (used when navigation consumes a prefetch) */
-  consume(url: string): PrefetchResult | undefined {
-    const result = this.get(url);
+  consume(key: PrefetchKey): PrefetchResult | undefined {
+    const result = this.get(key);
     if (result !== undefined) {
-      this.entries.delete(url);
+      this.entries.delete(prefetchMapKey(key));
     }
     return result;
   }
+
+  /**
+   * Store a negative entry — the URL is not a route (non-RSC Content-Type).
+   *
+   * Keyed like every other entry even though "not a route" does not actually
+   * vary by departing URL: a source-independent negative would be a second
+   * keying rule to keep correct, and the only cost of the uniform one is a
+   * repeated fetch for a link hovered from a second page.
+   */
+  setNegative(key: PrefetchKey): void {
+    this.set(key, NEGATIVE_ENTRY);
+  }
+
+  /** Check if the entry is a negative cache entry (URL is not a route). */
+  isNegative(key: PrefetchKey): boolean {
+    return this.get(key) === NEGATIVE_ENTRY;
+  }
 }

package/src/client/segment-outlet.tsx

@@ -0,0 +1,141 @@
+/**
+ * SegmentOutlet — client component boundary at each layout segment.
+ *
+ * Each layout in the segment tree is wrapped with a SegmentOutlet that:
+ * 1. Knows its segment path (prop from the server)
+ * 2. Reads from SegmentUpdateContext for partial navigation updates
+ * 3. Caches its rendered content in a ref across navigations
+ *
+ * On full navigation: receives new children via props, caches and renders them.
+ * On partial navigation (this segment skipped): the context map has no entry
+ * for this path, so the outlet returns cached content — preserving layout state.
+ * On partial navigation (this segment updated): the context map has content
+ * for this path, so the outlet renders the update.
+ *
+ * Uses React context instead of useSyncExternalStore to stay compatible
+ * with concurrent rendering (transitions). All outlets re-render when the
+ * context value changes, but each bails out quickly if its segment has
+ * no update — same approach as Next.js LayoutRouter.
+ *
+ * Security: performance optimization only. The server always runs all
+ * access.ts files regardless of segment skipping.
+ * See design/13-security.md §"State tree manipulation".
+ */
+
+'use client';
+
+import { useContext, useRef, type ReactNode } from 'react';
+import { SegmentUpdateContext } from './segment-update-context.js';
+
+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. 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;
+}
+
+// ─── Slot Content Cache ──────────────────────────────────────────
+// Persists slot content across SegmentOutlet fiber lifecycles.
+// When React creates new fibers during full navigation (e.g., the
+// server sends a complete new tree and React remounts the subtree),
+// useRef starts fresh with null. Skipped slots (skip=true, children=null)
+// would lose their cached content because contentRef.current is null.
+//
+// This globalThis-backed Map provides a fallback: SegmentOutlet stores
+// rendered content here whenever it renders non-null slot content, and
+// reads from it when skip=true but contentRef.current is null.
+//
+// Uses globalThis + Symbol.for for singleton guarantee across chunks —
+// same pattern as NavigationContext and SegmentUpdateContext.
+//
+// SSR safety: SegmentOutlet is 'use client' — during RSC rendering it's
+// serialized as a client reference and never executed. During SSR
+// (renderToReadableStream), the component IS executed but skip=true is
+// never sent (the server always renders full content). The cache may
+// accumulate entries during SSR but they're harmless — the skip=true
+// fallback path only activates on the client during SPA navigation.
+
+const SLOT_CACHE_KEY = Symbol.for('__timber_slot_content_cache');
+
+function getSlotContentCache(): Map<string, ReactNode> {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[SLOT_CACHE_KEY]) {
+    g[SLOT_CACHE_KEY] = new Map<string, ReactNode>();
+  }
+  return g[SLOT_CACHE_KEY] as Map<string, ReactNode>;
+}
+
+/**
+ * Client component boundary at each layout segment in the element tree.
+ *
+ * On full navigation (context map is empty): renders children, caches in ref.
+ * On partial navigation: checks the context map for an update at segmentPath.
+ *   - Update found → renders update, caches in ref.
+ *   - No update → returns cached content (layout state preserved).
+ *
+ * React preserves component instances across reactRoot.render() calls
+ * 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, skip }: SegmentOutletProps) {
+  const updates = useContext(SegmentUpdateContext);
+  const contentRef = useRef<ReactNode>(null);
+  const slotCache = getSlotContentCache();
+
+  const update = updates.get(segmentPath);
+
+  if (update !== undefined) {
+    contentRef.current = update;
+    slotCache.set(segmentPath, update);
+    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;
+    }
+    // Fiber was remounted (contentRef is fresh null). Fall back to the
+    // globalThis-backed cache which persists across fiber lifecycles.
+    if (slotCache.has(segmentPath)) {
+      const cached = slotCache.get(segmentPath)!;
+      contentRef.current = cached;
+      return cached;
+    }
+    // No cached content anywhere — the SegmentOutlet instance is fresh
+    // and no prior render has populated the cache. Fall through to render
+    // children (null). The slot will be fully rendered next navigation.
+  }
+
+  if (contentRef.current === null) {
+    contentRef.current = children;
+    slotCache.set(segmentPath, children);
+    return children;
+  }
+
+  if (children !== contentRef.current) {
+    contentRef.current = children;
+    slotCache.set(segmentPath, children);
+    return children;
+  }
+
+  return contentRef.current;
+}

package/src/client/segment-update-context.ts

@@ -0,0 +1,42 @@
+/**
+ * SegmentUpdateContext — React context for partial navigation updates.
+ *
+ * During partial navigation (server skips unchanged sync layouts), the
+ * router builds a Map of segment path → ReactNode updates and passes it
+ * as the context value. Mounted SegmentOutlet components read from this
+ * context to decide whether to render the update or their cached content.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. The RSC client bundler can duplicate this module
+ * across chunks (browser-entry graph + client-reference graph). With
+ * ESM output, each chunk gets its own module scope — a bare createContext
+ * at module level would create separate instances per chunk. globalThis
+ * guarantees a single instance regardless of duplication.
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export const EMPTY_SEGMENT_UPDATES = new Map<string, ReactNode>();
+
+const CTX_KEY = Symbol.for('__timber_segment_update_ctx');
+
+function getOrCreateContext(): React.Context<Map<string, ReactNode>> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<Map<string, ReactNode>>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<Map<string, ReactNode>>(EMPTY_SEGMENT_UPDATES);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  // RSC environment — createContext not available. Return a dummy that
+  // won't be used (outlets only render on the client).
+  return undefined as unknown as React.Context<Map<string, ReactNode>>;
+}
+
+export const SegmentUpdateContext = getOrCreateContext();

package/src/client/shallow-url.ts

@@ -0,0 +1,22 @@
+/**
+ * Shallow URL replacement — update the browser URL bar without triggering
+ * RSC navigation, TopLoader, or any server round-trip.
+ *
+ * Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+ * which the navigate event handler intercepts with a no-op handler. Falls back
+ * to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
+ */
+
+import { getNavigationApi } from './navigation-api.js';
+
+export function replaceUrl(url: string): void {
+  const nav = getNavigationApi();
+  if (nav) {
+    nav.navigate(url, {
+      history: 'replace',
+      info: { shallow: true },
+    });
+  } else {
+    history.replaceState(history.state, '', url);
+  }
+}

package/src/client/slot-context.ts

@@ -0,0 +1,50 @@
+/**
+ * SlotContext — delivers live slot content to SlotOutlet holes inside
+ * cached component shells (TIM-1173).
+ *
+ * A `cache.component(Fn, { slots: [...] })` shell is captured with a
+ * stable <SlotOutlet slot={name} /> client reference in place of each
+ * declared slot prop. At request time the revived shell is wrapped in a
+ * SlotsProvider carrying the live slot values; each outlet reads its
+ * value from this context by name.
+ *
+ * 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 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.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export type SlotValues = Record<string, ReactNode>;
+
+const CTX_KEY = Symbol.for('__timber_slot_ctx');
+
+function getOrCreateContext(): React.Context<SlotValues | null> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<SlotValues | null>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<SlotValues | null>(null);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  return undefined as unknown as React.Context<SlotValues | null>;
+}
+
+export const SlotContext = getOrCreateContext();

package/src/client/slot-outlet.tsx

@@ -0,0 +1,22 @@
+/**
+ * SlotOutlet — the hole in a cached component shell (TIM-1173).
+ *
+ * At capture time the prebuilt runtime renders the wrapped component with
+ * <SlotOutlet slot={name} /> in place of each declared slot prop. Being a
+ * client component, it serializes into the flight payload as a stable,
+ * deterministic client reference — the same bytes regardless of what live
+ * content will fill the hole. At request time the revived shell sits under
+ * a SlotsProvider and each outlet reads its live value from SlotContext.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { useContext } from 'react';
+import { SlotContext } from './slot-context.js';
+
+export function SlotOutlet({ slot }: { slot: string }) {
+  const values = useContext(SlotContext);
+  return values ? (values[slot] ?? null) : null;
+}