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

package/src/server/prebuilt-runtime.ts

@@ -0,0 +1,731 @@
+/**
+ * Prebuilt component runtime — registration target for the timber-prebuilt
+ * transform (plugins/prebuilt.ts) and the request-time half of
+ * cache.component (TIM-1140).
+ *
+ * `cache.component(fn, opts)` call sites are rewritten at build time to
+ * `__prebuilt(stableId, fn, opts)` (production) or `__prebuiltDev(name, fn)`
+ * (dev). Both are exported via #server-internal — they are framework
+ * plumbing, never called by user code directly.
+ *
+ * Cache hits are served by FLIGHT REVIVAL: the cached `.flight` payload is
+ * decoded back into React elements inside the RSC environment with
+ * `createFromReadableStream` (the flight client running in the flight
+ * server — plugin-rsc wires the server-decode manifest so client
+ * references revive as re-serializable reference proxies). The revived
+ * element is returned from the wrapper and the outer render re-serializes
+ * it like any other subtree. This is the same mechanism as Next.js
+ * `"use cache"` (next/src/server/use-cache/use-cache-wrapper.ts).
+ *
+ * What a hit skips: all user work — data fetching, MDX compilation, the
+ * component function itself never runs. What it re-pays: React
+ * re-serializes the already-resolved tree (cost proportional to payload
+ * size, not to data latency). The alternative — splicing raw payload bytes
+ * into the outer stream — avoids re-serialization but requires byte-level
+ * coupling to the flight wire format (row framing, ID rebasing, marker
+ * detection); it was implemented and reviewed on PR #835 and deliberately
+ * replaced by revival. See design/44-render-at-build-time.md
+ * §Request-Time Injection.
+ *
+ * Misses render the original component live via the wrapper's own closure,
+ * inside the React pass — segment params from ALS, deny()/redirect()
+ * signals, Suspense, and error boundaries behave exactly as an unwrapped
+ * component. `fallbackOnMissingSegmentParams: false` throws instead.
+ */
+
+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,
+  beginCapture,
+  endCapture,
+} from './prebuilt/capture-state.js';
+import {
+  hasPrebuiltPayloadSource,
+  lookupPrebuiltPayload,
+  getManifestEntry,
+  isParamIndependent,
+} from './prebuilt/payload-source.js';
+import { lookupOverlay, storeOverlayEntry, overlayKey } from './prebuilt/overlay.js';
+import { getWaitUntil } from './waituntil-bridge.js';
+import { createSingleflight } from '../cache/singleflight.js';
+import {
+  currentInvalidationEpoch,
+  wasInvalidatedSince,
+  lastInvalidationEpochFor,
+} from '../cache/invalidation-epoch.js';
+
+/** Default timeout for component re-renders (overridden by renderTimeoutMs). */
+const DEFAULT_COMPONENT_TIMEOUT_MS = 30_000;
+
+/** Singleflight for component re-renders (inline and background). */
+let componentSingleflight = createSingleflight({ timeoutMs: DEFAULT_COMPONENT_TIMEOUT_MS });
+let componentTimeoutMs = DEFAULT_COMPONENT_TIMEOUT_MS;
+
+/**
+ * Set the timeout for component re-render captures. Called at boot from
+ * the RSC entry with renderTimeoutMs from timber.config.ts.
+ */
+export function setComponentRefreshTimeout(timeoutMs: number): void {
+  componentTimeoutMs = timeoutMs;
+  componentSingleflight = createSingleflight({ timeoutMs });
+}
+
+let warnedNoWaitUntil = false;
+
+/**
+ * Options captured from the `cache.component(fn, opts)` call site.
+ *
+ * `prerender`/`ttl`/`tags` (design/45) are carried through untouched — the
+ * build phase (TIM-1119) and runtime overlay (design/45 phase 3) consume
+ * them.
+ */
+export interface PrebuiltComponentOptions {
+  /** Populate the cache at build time via generateStaticSegmentParams. */
+  prerender?: boolean;
+  /** Runtime freshness window, seconds (design/45 runtime tier). */
+  ttl?: number;
+  /** Runtime invalidation tags (design/45 runtime tier). */
+  tags?: string[] | ((props: Record<string, unknown>) => string[]);
+  /** Serve stale while a background re-render refreshes (design/45 §SWR). */
+  staleWhileRevalidate?: boolean;
+  /**
+   * On a cache miss, render the component live (default: true). When false,
+   * a miss throws instead — for sites that must never render unknown params
+   * dynamically. See design/44 §fallbackOnMissingSegmentParams.
+   */
+  fallbackOnMissingSegmentParams?: boolean;
+}
+
+/** An async server component: props in, renderable out. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ServerComponent = (props: any) => unknown;
+
+/**
+ * View of a ServerComponent that satisfies createElement's overloads.
+ * Server components legitimately return `unknown` from the framework's
+ * perspective (promises, elements, strings, …) — React renders whatever
+ * comes back; the narrowing exists only to cross createElement's
+ * ReactNode-typed signature.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RenderableComponent = (props: any) => React.ReactNode;
+
+export interface PrebuiltRegistration {
+  id: string;
+  component: ServerComponent;
+  options: PrebuiltComponentOptions;
+}
+
+/**
+ * Server-side component registry, keyed by stable component ID. Populated at
+ * module load time by `__prebuilt` calls; consumed by the post-build capture
+ * pass (TIM-1119). Never serialized — component functions are not
+ * Flight-serializable.
+ */
+const registry = new Map<string, PrebuiltRegistration>();
+
+/**
+ * Resolve the params the cache key may faithfully hash, or null if this
+ * render is unkeyable.
+ *
+ * A wrapper rendered inside a parallel slot reads params merged with that
+ * slot's overrides (`getSegmentParams`: `{...segmentParams, ...slotParams}`)
+ * — but the cache key hashes only the route-level params, and the wrapper
+ * cannot know which slot it renders under. The route params are usable
+ * only when every slot's merged view canonicalizes identically to them;
+ * otherwise two renders with the same key could see different effective
+ * inputs and a hit could serve the WRONG cached subtree — so the render
+ * goes live: slower, never wrong. (Build-time capture doesn't model slot
+ * params either, so a divergent request could never have a faithful
+ * entry. Codex review on PR #835; revisit with segment-path-scoped keys
+ * if slot-scoped prebuilt is ever needed.)
+ *
+ * Comparison happens through `tryCanonicalize` — the same single
+ * definition of value equality the cache key uses — so anything it
+ * cannot represent faithfully (bigint-coerced codec params, accessors,
+ * aliases, …) is unkeyable here too, and this guard can never throw.
+ */
+function resolveKeyParams(store: {
+  segmentParams?: Record<string, string | string[]>;
+  slotParamsMap?: Map<string, Record<string, string | string[]>>;
+}): Record<string, string | string[]> | null {
+  const main = store.segmentParams ?? {};
+  const map = store.slotParamsMap;
+  if (!map || map.size === 0) return main;
+  // Spread before canonicalizing: param records are framework-produced
+  // Object.create(null) objects (prototype-pollution defense) — normalize
+  // the records themselves, let nested values face the full allowlist.
+  const mainCanonical = tryCanonicalize({ ...main });
+  if (mainCanonical === null) return null;
+  for (const slotParams of map.values()) {
+    const merged = tryCanonicalize({ ...main, ...slotParams });
+    if (merged === null || merged !== mainCanonical) return null;
+  }
+  return main;
+}
+
+/** Wrap payload bytes as a single-chunk ReadableStream for the decoder. */
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/** Whether the component has a runtime lifetime (ttl or tags). */
+function hasRuntimeLifetime(options: PrebuiltComponentOptions): boolean {
+  return options.ttl !== undefined || (options.tags !== undefined && options.tags !== null);
+}
+
+/** Resolve tags from options (may be static array or function of props). */
+function resolveTags(options: PrebuiltComponentOptions, props: Record<string, unknown>): string[] {
+  if (!options.tags) return [];
+  if (Array.isArray(options.tags)) return options.tags;
+  return options.tags(props);
+}
+
+// ─── RSC function injection ─────────────────────────────────────────────
+// The flight client/server is only resolvable in the RSC environment
+// (react-server condition). The RSC entry wires these at boot via
+// setRscFunctions(); tests inject mocks directly. Same pattern as
+// setCacheHandler / setPrebuiltPayloadSource.
+
+interface RscFunctions {
+  createFromReadableStream: (stream: ReadableStream<Uint8Array>) => Promise<unknown>;
+  renderToReadableStream: (
+    element: unknown,
+    options?: { onError?: (error: unknown) => string }
+  ) => ReadableStream<Uint8Array>;
+}
+
+let rscFns: RscFunctions | null = null;
+
+/**
+ * Wire the RSC flight client/server functions. Called once at server
+ * startup from the RSC entry module.
+ */
+export function setRscFunctions(fns: RscFunctions): void {
+  rscFns = fns;
+}
+
+function requireRscFunctions(): RscFunctions {
+  if (!rscFns) {
+    throw new Error('[timber] RSC functions not wired — setRscFunctions() must be called at boot');
+  }
+  return rscFns;
+}
+
+/**
+ * Revive flight payload bytes into a React element.
+ * Returns null on any failure (corrupt payload, missing decoder).
+ */
+async function revivePayload(
+  id: string,
+  payload: Uint8Array,
+  outcome: string
+): Promise<{ element: unknown } | null> {
+  try {
+    const { createFromReadableStream } = requireRscFunctions();
+    const element: unknown = await createFromReadableStream(bytesToStream(payload));
+    return { element };
+  } catch (error) {
+    console.error(`[timber] failed to revive prebuilt payload for "${id}" — ${outcome}:`, error);
+    return null;
+  }
+}
+
+/** Ceiling on component re-render capture (design/13 A2). Uses configured renderTimeoutMs. */
+function getCaptureTimeoutMs(): number {
+  return componentTimeoutMs;
+}
+
+// ─── Key-discipline warnings (design/45 §Enforcement) ───────────────────
+
+export const keyDisciplineWarned = new Set<string>();
+
+const REQUEST_CONTEXT_FIELDS: Record<string, string> = {
+  headers: 'headers()',
+  parsedCookies: 'cookies()',
+  searchParams: 'searchParams',
+};
+
+/**
+ * Wrap a store with a proxy that records per-request field access.
+ * The proxy forwards all reads/writes transparently — it only observes.
+ */
+function createKeyDisciplineProxy(store: RequestContextStore): {
+  proxy: RequestContextStore;
+  accessedApis: Set<string>;
+} {
+  const accessedApis = new Set<string>();
+  const proxy = new Proxy(store, {
+    get(target, prop, receiver) {
+      const api = REQUEST_CONTEXT_FIELDS[prop as string];
+      if (api) accessedApis.add(api);
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+  return { proxy, accessedApis };
+}
+
+function emitKeyDisciplineWarning(id: string, apis: Set<string>): void {
+  if (keyDisciplineWarned.has(id)) return;
+  keyDisciplineWarned.add(id);
+  const apiList = Array.from(apis).join(', ');
+  console.warn(
+    `[timber] cache.component key-discipline warning: "${id}" reads ${apiList} ` +
+      `but the cache key is computed from props and segment params only. ` +
+      `If the output varies by ${apiList}, different users may see each ` +
+      `other's cached content. Either pass request-derived values as ` +
+      `props (included in the cache key) or remove the ${apiList} call.`
+  );
+}
+
+/**
+ * Render a component in isolation and capture its flight payload bytes.
+ * Used for inline re-renders (tombstone/miss) and SWR background re-renders.
+ *
+ * The stream read is timeout-guarded and the reader is cancelled on
+ * expiry (design/13 A2, A3).
+ */
+async function captureComponentPayload(
+  id: string,
+  component: ServerComponent,
+  props: Record<string, unknown>
+): Promise<Uint8Array> {
+  const { renderToReadableStream } = requireRscFunctions();
+  const element = createElement(component as RenderableComponent, props);
+  // Activate capture state so nested cache.component wrappers render live
+  // (bake flat into this entry) per design/45 §Nesting Semantics.
+  // beginCapture/endCapture MUST be in the same try/finally to prevent
+  // leaked capture state on early throws.
+  let renderErrored = false;
+
+  // Key-discipline diagnostic (design/45 §Enforcement): proxy the ALS
+  // store to detect request-context reads during the capture render.
+  // The proxy is transparent — it never blocks or throws; it only observes.
+  const store = requestContextAls.getStore();
+  const discipline = store && !keyDisciplineWarned.has(id) ? createKeyDisciplineProxy(store) : null;
+
+  const doCapture = async (): Promise<Uint8Array> => {
+    beginCapture(id);
+    try {
+      const stream: ReadableStream<Uint8Array> = renderToReadableStream(element, {
+        onError() {
+          renderErrored = true;
+          return '';
+        },
+      });
+      const reader = stream.getReader();
+      const chunks: Uint8Array[] = [];
+      let totalLength = 0;
+      const deadline = Date.now() + getCaptureTimeoutMs();
+      try {
+        for (;;) {
+          const remaining = deadline - Date.now();
+          if (remaining <= 0) {
+            throw new Error(
+              `[timber] component re-render capture exceeded ${getCaptureTimeoutMs()}ms`
+            );
+          }
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          const { done, value } = await Promise.race([
+            reader.read(),
+            new Promise<never>((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error(`[timber] component re-render stream read timed out`)),
+                remaining
+              );
+            }),
+          ]);
+          clearTimeout(timer);
+          if (done) break;
+          chunks.push(value);
+          totalLength += value.byteLength;
+        }
+      } finally {
+        reader.cancel().catch(() => {});
+      }
+      if (renderErrored) {
+        throw new Error('[timber] component re-render produced error rows — not caching');
+      }
+      const result = new Uint8Array(totalLength);
+      let offset = 0;
+      for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      return result;
+    } finally {
+      endCapture();
+    }
+  };
+
+  const bytes = discipline
+    ? await requestContextAls.run(discipline.proxy, doCapture)
+    : await doCapture();
+
+  if (discipline && discipline.accessedApis.size > 0) {
+    emitKeyDisciplineWarning(id, discipline.accessedApis);
+  }
+
+  return bytes;
+}
+
+/**
+ * Inline re-render: capture flight bytes, store in overlay, revive for
+ * the current request. Singleflight-coalesced by overlay key.
+ */
+async function inlineRerender(
+  id: string,
+  component: ServerComponent,
+  props: Record<string, unknown>,
+  cacheKey: string,
+  options: PrebuiltComponentOptions,
+  hasSeed: boolean,
+  outcome: string
+): Promise<{ element: unknown } | null> {
+  const tags = resolveTags(options, props);
+  const oKey = overlayKey(id, cacheKey);
+  const sfKey = `prebuilt:${id}:${cacheKey}\0${lastInvalidationEpochFor(oKey, tags)}`;
+
+  try {
+    const payload = await componentSingleflight.do(sfKey, async (signal) => {
+      const startEpoch = currentInvalidationEpoch();
+      const bytes = await captureComponentPayload(id, component, props);
+      // Skip the store if aborted (singleflight timeout) or if the
+      // key/tags were invalidated while rendering (TIM-1028 guard).
+      if (
+        !signal.aborted &&
+        hasRuntimeLifetime(options) &&
+        !wasInvalidatedSince(startEpoch, oKey, tags)
+      ) {
+        await storeOverlayEntry(id, cacheKey, bytes, {
+          ttl: options.ttl,
+          tags,
+          hasSeed,
+        });
+      }
+      return bytes;
+    });
+    return await revivePayload(id, payload, outcome);
+  } catch (error) {
+    console.error(`[timber] cache.component re-render failed for "${id}" — ${outcome}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Snapshot the request context values needed for a background re-render.
+ * Creates a FRESH store with copied values — the original ALS store is
+ * not referenced after capture.
+ */
+function snapshotRequestContext(store: RequestContextStore): RequestContextStore {
+  return {
+    headers: new Headers(store.headers),
+    originalHeaders: new Headers(store.originalHeaders),
+    cookieHeader: store.cookieHeader,
+    parsedCookies: store.parsedCookies ? new Map(store.parsedCookies) : undefined,
+    searchParams: new URLSearchParams(store.searchParams),
+    searchString: store.searchString,
+    segmentParams: store.segmentParams ? { ...store.segmentParams } : undefined,
+    cookieJar: new Map(),
+    flushed: false,
+    mutableContext: false,
+  };
+}
+
+/**
+ * Kick off a background re-render via waitUntil. The re-render runs inside
+ * a fresh ALS scope with snapshotted request context.
+ */
+function backgroundRerender(
+  id: string,
+  component: ServerComponent,
+  props: Record<string, unknown>,
+  cacheKey: string,
+  options: PrebuiltComponentOptions,
+  hasSeed: boolean,
+  snapshot: RequestContextStore
+): void {
+  const waitUntil = getWaitUntil();
+  const tags = resolveTags(options, props);
+  const oKey = overlayKey(id, cacheKey);
+  const startEpoch = currentInvalidationEpoch();
+  const sfKey = `prebuilt-bg:${id}:${cacheKey}\0${lastInvalidationEpochFor(oKey, tags)}`;
+
+  const work = requestContextAls.run(snapshot, () =>
+    componentSingleflight
+      .do(sfKey, async (signal) => {
+        const bytes = await captureComponentPayload(id, component, props);
+        if (!signal.aborted && !wasInvalidatedSince(startEpoch, oKey, tags)) {
+          await storeOverlayEntry(id, cacheKey, bytes, {
+            ttl: options.ttl,
+            tags,
+            hasSeed,
+          });
+        }
+      })
+      .catch((error) => {
+        console.error(`[timber] cache.component background re-render failed for "${id}":`, error);
+      })
+  );
+
+  if (waitUntil) {
+    waitUntil(work);
+  } else if (!warnedNoWaitUntil) {
+    warnedNoWaitUntil = true;
+    console.warn(
+      '[timber] cache.component SWR background re-render has no waitUntil — ' +
+        'the re-render may be killed when the handler returns on serverless platforms. ' +
+        'Ensure the adapter wires runWithWaitUntil().'
+    );
+  }
+}
+
+/**
+ * Try to serve this render from the prebuilt cache: overlay → artifact →
+ * live render. Handles ISR (SWR, tombstones, re-renders) per design/45.
+ *
+ * Null on any miss — the caller renders live.
+ */
+async function tryRevivePayload(
+  id: string,
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): Promise<{ element: unknown } | null> {
+  const hasSource = hasPrebuiltPayloadSource();
+  const hasRuntime = hasRuntimeLifetime(options);
+  if (!hasSource && !hasRuntime) return null;
+
+  const store = requestContextAls.getStore();
+  if (!store) return null;
+  const paramIndep = options.prerender ? await isParamIndependent(id) : false;
+  const keyParams = paramIndep ? {} : resolveKeyParams(store);
+  if (keyParams === null) return null;
+
+  // 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 =
+    options.fallbackOnMissingSegmentParams === false
+      ? 'failing the render (fallbackOnMissingSegmentParams: false)'
+      : 'rendering dynamically';
+
+  const registration = registry.get(id);
+  const component = registration?.component;
+
+  // ─── Step 1: Check overlay (CacheHandler) ─────────────────────────
+  if (hasRuntime) {
+    const overlayResult = await lookupOverlay(id, cacheKey);
+    if (overlayResult) {
+      const overlayHasSeed = overlayResult.record?.s ?? false;
+      if (overlayResult.kind === 'tombstone') {
+        if (component) {
+          return await inlineRerender(id, component, props, cacheKey, options, true, outcome);
+        }
+        return null;
+      }
+      if (overlayResult.kind === 'fresh' && overlayResult.payload) {
+        return await revivePayload(id, overlayResult.payload, outcome);
+      }
+      if (overlayResult.kind === 'stale' && overlayResult.payload) {
+        if (options.staleWhileRevalidate && component) {
+          backgroundRerender(
+            id,
+            component,
+            props,
+            cacheKey,
+            options,
+            overlayHasSeed,
+            snapshotRequestContext(store)
+          );
+          return await revivePayload(id, overlayResult.payload, outcome);
+        }
+        if (component) {
+          return await inlineRerender(
+            id,
+            component,
+            props,
+            cacheKey,
+            options,
+            overlayHasSeed,
+            outcome
+          );
+        }
+        return null;
+      }
+    }
+  }
+
+  // ─── Step 2: Check build artifact ─────────────────────────────────
+  if (hasSource) {
+    const artifactPayload = await lookupPrebuiltPayload(id, cacheKey);
+    if (artifactPayload !== null) {
+      // Check seed freshness when the component has a TTL.
+      if (options.ttl !== undefined) {
+        const entry = await getManifestEntry(id, cacheKey);
+        const buildTs = entry?.buildTimestamp ?? 0;
+        const seedAge = (Date.now() - buildTs) / 1000;
+        if (seedAge > options.ttl) {
+          // Stale seed
+          if (options.staleWhileRevalidate && component) {
+            backgroundRerender(
+              id,
+              component,
+              props,
+              cacheKey,
+              options,
+              true,
+              snapshotRequestContext(store)
+            );
+            return await revivePayload(id, artifactPayload, outcome);
+          }
+          if (component) {
+            return await inlineRerender(id, component, props, cacheKey, options, true, outcome);
+          }
+          // No component in registry — can't re-render; fall through to
+          // live render via the wrapper (design/45 step 3).
+          return null;
+        }
+      }
+      // Fresh seed (or no TTL — immutable until redeploy)
+      return await revivePayload(id, artifactPayload, outcome);
+    }
+
+    // Manifest miss
+    if (options.prerender) {
+      console.warn(
+        `[timber] cache.component cache miss: "${id}" with params ${JSON.stringify(
+          store.segmentParams ?? {}
+        )} — ${outcome}`
+      );
+    }
+  }
+
+  // ─── Step 3: Full miss with runtime lifetime — inline re-render ───
+  // Skip when fallbackOnMissingSegmentParams is false — that option means
+  // "only prebuilt content", so an unenumerated miss must throw (the
+  // wrapper handles the throw after we return null).
+  if (hasRuntime && component && options.fallbackOnMissingSegmentParams !== false) {
+    return await inlineRerender(id, component, props, cacheKey, options, false, outcome);
+  }
+
+  return null;
+}
+
+/**
+ * Production wrapper injected by the timber-prebuilt transform. Registers
+ * the component under its stable ID and returns a wrapper component that
+ * either revives the cached payload (hit) or renders the original
+ * component live (miss).
+ */
+export function __prebuilt<C extends ServerComponent>(
+  id: string,
+  component: C,
+  options: PrebuiltComponentOptions = {}
+): C {
+  registry.set(id, { id, component, options });
+
+  const wrapper = async (props: Parameters<C>[0]) => {
+    // Build-time only: report this render to the active capture pass —
+    // cycle detection (throws) and nesting-clamp warnings (design/45
+    // §Nesting Semantics). A single null-check at request time.
+    noteWrapperRender(id, options);
+    if (isCaptureActive()) {
+      // Nested wrapper inside a build-time capture: render live so the
+      // subtree bakes flat into the enclosing entry (design/45 §Nesting).
+      // This deliberately bypasses fallbackOnMissingSegmentParams: false —
+      // that option means "never serve non-prebuilt content", and a
+      // build-time render IS prebuilt content; throwing here would
+      // spuriously fail the outer entry (codex P2 on PR #836).
+      return createElement(component as RenderableComponent, props as Record<string, unknown>);
+    }
+    const revived = await tryRevivePayload(id, options, props as Record<string, unknown>);
+    if (revived !== null) {
+      return revived.element;
+    }
+    if (options.fallbackOnMissingSegmentParams === false) {
+      throw new Error(
+        `[timber] cache.component "${id}": no prebuilt payload for the current params and fallbackOnMissingSegmentParams is false`
+      );
+    }
+    // Return an ELEMENT — React invokes the component itself, with its
+    // render dispatcher active. Calling component(props) here would run
+    // it after this wrapper's await, outside a dispatcher frame, breaking
+    // sync server components that call use() (codex review on PR #835).
+    return createElement(component as RenderableComponent, props as Record<string, unknown>);
+  };
+  Object.defineProperty(wrapper, 'name', { value: `Prebuilt(${id})` });
+  // Double cast, deliberately: C's return type may be narrower than the
+  // wrapper's (a sync component wrapped by an async function, or a revived
+  // subtree in place of C's exact JSX type). Callers only ever *render*
+  // the result — React treats any component returning ReactNode-compatible
+  // values identically — so widening through `unknown` is safe here and a
+  // direct cast would be rejected by the compiler for exactly the
+  // difference we intend.
+  return wrapper as unknown as C;
+}
+
+/** Look up a registration by stable component ID. */
+export function getPrebuiltRegistration(id: string): PrebuiltRegistration | undefined {
+  return registry.get(id);
+}
+
+/** All registrations, for the post-build capture pass (TIM-1119). */
+export function getPrebuiltRegistry(): ReadonlyMap<string, PrebuiltRegistration> {
+  return registry;
+}
+
+/**
+ * Dev-mode wrapper injected by the timber-prebuilt transform: a no-op that
+ * renders the component dynamically on every request, logging once per
+ * component on first render so the production behavior difference is visible.
+ * See design/44 §Dev Mode.
+ */
+export function __prebuiltDev<C extends ServerComponent>(
+  name: string,
+  component: C,
+  _options?: PrebuiltComponentOptions
+): C {
+  let logged = false;
+  const wrapper = (props: Parameters<C>[0]) => {
+    if (!logged) {
+      logged = true;
+      console.log(`[timber] cache.component: "${name}" — rendering dynamically (dev mode)`);
+    }
+    // Element, not a direct call — same dispatcher reasoning as the
+    // production wrapper's live fallback.
+    return createElement(component as RenderableComponent, props as Record<string, unknown>);
+  };
+  return wrapper as C;
+}