@timber-js/app 0.2.0-alpha.208 → 0.2.0-alpha.209

package/src/server/prebuilt-builder.ts

@@ -42,33 +42,26 @@
  *     → skip that entry, warn, keep building.
  */
 
-import { createElement } from 'react';
-
-import { requestContextAls } from './als-registry.ts';
 import type { CoercedParams } from '../shared/param-value.ts';
 import { ParamCoercionError } from './param-coercion.ts';
-import { SlotOutlet } from '../client/slot-outlet.tsx';
 import { coerceSegmentParams } from './param-coercion.ts';
-import { isDenySignal, isRedirectSignal } from './primitives.ts';
-import {
-  beginCapture,
-  endCapture,
-  PrebuiltCaptureCycleError,
-  type NestedWrapperRender,
-} from './prebuilt/capture-state.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
 import { computeComponentCacheKey } from './prebuilt/cache-key.ts';
-import { LAYOUT_CHILDREN_SLOT } from './prebuilt/slots.ts';
-import { BuildTimeContextError, createBuildTimeStore } from './prebuilt/synthetic-store.ts';
+import { bytesToStream, renderEntry } from './prebuilt/capture-render.ts';
 import {
-  getPrebuiltRegistration,
-  type PrebuiltComponentOptions,
-  type PrebuiltRegistration,
-} from './prebuilt-runtime.ts';
+  collectCandidateRoutes,
+  enumerateCombos,
+  type ParamCombo,
+} from './prebuilt/capture-routes.ts';
+import { warnNestingClamps } from './prebuilt/lifetime.ts';
+import { BuildTimeContextError } from './prebuilt/synthetic-store.ts';
+import { getPrebuiltRegistration } from './prebuilt-runtime.ts';
 import { createRouteMatcher } from './route-matcher.ts';
-import type { ManifestFile, ManifestRoot, ManifestSegmentNode } from './route-matcher.ts';
-import { createFromReadableStream, renderToReadableStream } from '../rsc-runtime/rsc.ts';
+import type { ManifestRoot } from './route-matcher.ts';
+import { createFromReadableStream } from '../rsc-runtime/rsc.ts';
 import { loadModule } from './safe-load.ts';
-import { hasDynamicSegments, resolvePathWithParams } from './sitemap-generator.ts';
+import { resolvePathWithParams } from './sitemap-generator.ts';
+import { resolveRenderTimeoutMs } from './render-timeout.ts';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -146,66 +139,6 @@ export interface CaptureOptions {
   log?: (message: string) => void;
 }
 
-const DEFAULT_RENDER_TIMEOUT_MS = 30_000;
-
-// ─── Route collection ─────────────────────────────────────────────────────
-
-interface CandidateRoute {
-  urlPath: string;
-  page: ManifestFile;
-  /** Layout files along the chain that declare prebuilt components. */
-  layoutsToLoad: ManifestFile[];
-  /** Component IDs attributed to this route's page + layout chain. */
-  componentIds: string[];
-  /** Component IDs from layout files (receive SlotOutlet as children). */
-  layoutComponentIds: Set<string>;
-}
-
-/**
- * Walk the manifest tree and collect pages whose file chain (page +
- * layouts above it) has prebuilt components attributed to it. Slots and
- * intercepting/private segments are not walked — slot-scoped prebuilt is
- * already unkeyable at request time when slot params diverge (see
- * resolveKeyParams in prebuilt-runtime.ts), so the build doesn't model
- * slots either.
- */
-function collectCandidateRoutes(
-  root: ManifestSegmentNode,
-  fileComponentMap: Record<string, string[]>
-): CandidateRoute[] {
-  const routes: CandidateRoute[] = [];
-
-  const walk = (node: ManifestSegmentNode, layoutChain: ManifestFile[]) => {
-    if (node.segmentType === 'intercepting' || node.segmentType === 'private') return;
-    const chain = node.layout ? [...layoutChain, node.layout] : layoutChain;
-
-    if (node.page) {
-      const componentIds = new Set<string>();
-      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,
-        });
-      }
-    }
-
-    for (const child of node.children) walk(child, chain);
-  };
-
-  walk(root, []);
-  return routes;
-}
-
 // ─── Lazy chunk loading ───────────────────────────────────────────────────
 
 /**
@@ -218,181 +151,6 @@ async function loadLazyChunk(chunkFile: string): Promise<void> {
   await import(/* @vite-ignore */ url);
 }
 
-// ─── Param enumeration ────────────────────────────────────────────────────
-
-type ParamCombo = CoercedParams;
-
-/**
- * Resolve the param combos to capture for a route. Static routes have
- * exactly one combo (the empty record) — `export const prerender`-style
- * components on static pages need no enumerator. Dynamic routes require
- * `generateStaticSegmentParams` (design/44 §generateStaticSegmentParams);
- * without it every request renders live and the wrapper is a no-op.
- */
-async function enumerateCombos(
-  route: CandidateRoute,
-  pageModule: Record<string, unknown>,
-  log: (message: string) => void
-): Promise<ParamCombo[] | null> {
-  if (!hasDynamicSegments(route.urlPath)) return [{}];
-
-  const generateFn = pageModule.generateStaticSegmentParams;
-  if (typeof generateFn !== 'function') {
-    log(
-      `[timber] cache.component: route ${route.urlPath} has prebuilt components but no ` +
-        `generateStaticSegmentParams export — all its entries will render dynamically ` +
-        `until the page declares its param combos`
-    );
-    return null;
-  }
-  const combos: unknown = await (generateFn as () => unknown)();
-  if (!Array.isArray(combos)) {
-    throw new Error(
-      `generateStaticSegmentParams must return an array of param records, got ${typeof combos}`
-    );
-  }
-  return combos as ParamCombo[];
-}
-
-// ─── Rendering ────────────────────────────────────────────────────────────
-
-function concatChunks(chunks: Uint8Array[]): Uint8Array {
-  let total = 0;
-  for (const c of chunks) total += c.byteLength;
-  const out = new Uint8Array(total);
-  let off = 0;
-  for (const c of chunks) {
-    out.set(c, off);
-    off += c.byteLength;
-  }
-  return out;
-}
-
-/**
- * Drain a flight stream to completion under a deadline. On timeout the
- * reader is cancelled (never abandoned mid-read — design/13 A2/A3) and
- * the entry fails.
- */
-async function drainWithTimeout(
-  stream: ReadableStream<Uint8Array>,
-  timeoutMs: number
-): Promise<Uint8Array> {
-  const reader = stream.getReader();
-  const chunks: Uint8Array[] = [];
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let timedOut = false;
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      timedOut = true;
-      reject(new Error(`render did not complete within ${timeoutMs}ms`));
-    }, timeoutMs);
-  });
-  try {
-    for (;;) {
-      const { done, value } = await Promise.race([reader.read(), deadline]);
-      if (done) break;
-      chunks.push(value as Uint8Array);
-    }
-  } finally {
-    clearTimeout(timer);
-    if (timedOut) await reader.cancel().catch(() => {});
-  }
-  return concatChunks(chunks);
-}
-
-/** Wrap payload bytes as a single-chunk stream for the smoke revival. */
-function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
-  return new ReadableStream({
-    start(c) {
-      c.enqueue(bytes);
-      c.close();
-    },
-  });
-}
-
-/**
- * View of a registered component that satisfies createElement — same
- * narrowing rationale as prebuilt-runtime.ts.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type RenderableComponent = (props: any) => React.ReactNode;
-
-interface EntryOutcome {
-  bytes: Uint8Array | null;
-  failure: unknown;
-  nested: NestedWrapperRender[];
-  resolvedTags: string[] | undefined;
-  segmentParamsRead: boolean;
-}
-
-/**
- * Render one (component, props, coerced-params) entry in isolation and drain
- * its flight payload. Any `onError` during serialization fails the entry —
- * a payload with an embedded error row would replay that error on every
- * future request, so only fully clean renders are captured.
- */
-async function renderEntry(
-  registration: PrebuiltRegistration,
-  props: Record<string, unknown>,
-  coercedParams: CoercedParams,
-  timeoutMs: number,
-  isLayout: boolean
-): Promise<EntryOutcome> {
-  const storeHandle = createBuildTimeStore(registration.id, coercedParams);
-  const { store, violations } = storeHandle;
-  let failure: unknown = null;
-
-  beginCapture(registration.id);
-  let bytes: Uint8Array | null = null;
-  let resolvedTags: string[] | undefined;
-  let nested: NestedWrapperRender[];
-  try {
-    // Render AND drain inside one ALS scope: flight executes components
-    // lazily as the stream is pulled, and each pull must still see the
-    // 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 <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(SlotOutlet, { slot: LAYOUT_CHILDREN_SLOT }) }
-        : props;
-    bytes = await requestContextAls.run(store, async () => {
-      const stream = renderToReadableStream(
-        createElement(registration.component as RenderableComponent, renderProps),
-        {
-          onError(error: unknown) {
-            failure ??= error ?? new Error('unknown render error');
-            // Digest string keeps flight from warning about a missing
-            // digest; the payload is discarded because `failure` is set.
-            return 'timber-prebuilt-capture-error';
-          },
-        }
-      );
-      const drained = await drainWithTimeout(stream, timeoutMs);
-      resolvedTags = resolveCapturedTags(registration.options, props);
-      return drained;
-    });
-  } catch (error) {
-    // Sync component throw (renderToReadableStream creation), drain
-    // timeout, or stream error.
-    failure ??= error;
-  } finally {
-    nested = endCapture();
-  }
-
-  // Side-channel check FIRST: a component that touched per-request context
-  // is a hard error even when it caught the throw and rendered a fallback —
-  // accepting that payload would bake the request-dependent branch for
-  // every future request (codex P1 on PR #836).
-  const { segmentParamsRead } = storeHandle;
-  if (violations.length > 0)
-    return { bytes: null, failure: violations[0], nested, resolvedTags, segmentParamsRead };
-  if (failure !== null) return { bytes: null, failure, nested, resolvedTags, segmentParamsRead };
-  return { bytes, failure: null, nested, resolvedTags, segmentParamsRead };
-}
-
 /** Human-readable classification for a failed entry. */
 function describeFailure(error: unknown): string {
   if (isDenySignal(error)) return `component called deny(${error.status})`;
@@ -401,63 +159,8 @@ function describeFailure(error: unknown): string {
   return String(error);
 }
 
-// ─── Nesting clamp warnings (design/45 §Nesting Semantics) ────────────────
-
-/** Render a lifetime declaration for the clamp warning. */
-function describeLifetime(options: PrebuiltComponentOptions): string {
-  const parts: string[] = [];
-  if (options.prerender) parts.push('prerender');
-  if (options.ttl !== undefined) parts.push(`ttl: ${options.ttl}`);
-  if (options.tags !== undefined) {
-    parts.push(
-      typeof options.tags === 'function' ? 'tags: fn' : `tags: ${JSON.stringify(options.tags)}`
-    );
-  }
-  return parts.join(', ') || 'no lifetime';
-}
-
-/**
- * Warn when an inner wrapped component declares a refresh channel the
- * enclosing prerendered entry cannot honor. The outer here is always
- * prerender-tier (that's all the build captures), whose effective
- * lifetime is deploy-long with no tags — so ANY inner ttl/tags warns.
- * Once per (outer, inner) pair per build.
- */
-function warnNestingClamps(
-  outerId: string,
-  nested: NestedWrapperRender[],
-  warnedPairs: Set<string>,
-  log: (message: string) => void
-): number {
-  let count = 0;
-  for (const { innerId, options } of nested) {
-    if (options.ttl === undefined && options.tags === undefined) continue;
-    const pairKey = `${outerId} ${innerId}`;
-    if (warnedPairs.has(pairKey)) continue;
-    warnedPairs.add(pairKey);
-    count++;
-    log(
-      `[timber] ${innerId} (${describeLifetime(options)}) is embedded in prerendered ` +
-        `${outerId} — the embedded copy refreshes only when ${outerId} does (on redeploy). ` +
-        `Runtime revalidation will NOT update the embedded copy; tag ${outerId} itself if ` +
-        `you need that. Chain: ${outerId} (prerender) → ${innerId} (${describeLifetime(options)})`
-    );
-  }
-  return count;
-}
-
 // ─── Capture orchestration ────────────────────────────────────────────────
 
-/** Resolve tags from callsite options — static arrays pass through, function tags are evaluated with the capture-time props. */
-function resolveCapturedTags(
-  options: PrebuiltComponentOptions,
-  props: Record<string, unknown>
-): string[] | undefined {
-  if (!options.tags) return undefined;
-  const resolved = typeof options.tags === 'function' ? options.tags(props) : options.tags;
-  return resolved.length > 0 ? resolved : undefined;
-}
-
 /** Buffered entry pending the param-independence decision (TIM-1175). */
 interface PendingEntry {
   callSiteProps: Record<string, unknown>;
@@ -488,7 +191,7 @@ export async function capturePrebuiltPayloads(
   options: CaptureOptions
 ): Promise<CaptureSummary> {
   const log = options.log ?? ((message: string) => console.warn(message));
-  const timeoutMs = options.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
+  const timeoutMs = resolveRenderTimeoutMs(options.renderTimeoutMs);
   const matchRoute = createRouteMatcher(manifest);
 
   const summary: CaptureSummary = { captured: 0, skipped: [], hardErrors: [], nestingWarnings: 0 };
@@ -588,8 +291,9 @@ export async function capturePrebuiltPayloads(
         });
         continue;
       }
+      let coercedParams: CoercedParams;
       try {
-        await coerceSegmentParams(match);
+        coercedParams = await coerceSegmentParams(match);
       } catch (error) {
         skip({
           componentId: route.componentIds[0],
@@ -602,7 +306,6 @@ export async function capturePrebuiltPayloads(
         });
         continue;
       }
-      const coercedParams = match.segmentParams;
 
       for (const componentId of route.componentIds) {
         let registration = getPrebuiltRegistration(componentId);
@@ -709,13 +412,6 @@ export async function capturePrebuiltPayloads(
           } else if (outcome.failure === null && !pending.anyParamRead) {
             provenParamIndependent.add(proofKey);
           }
-          summary.nestingWarnings += warnNestingClamps(
-            componentId,
-            outcome.nested,
-            warnedPairs,
-            log
-          );
-
           if (outcome.failure !== null) {
             const issue: CaptureIssue = {
               componentId,
@@ -748,6 +444,20 @@ export async function capturePrebuiltPayloads(
             continue;
           }
 
+          // Clamp warnings for an accepted entry only: a skipped one stores
+          // nothing to clamp (and a failed render never resolved its tags),
+          // and must not spend the pair's one warning.
+          summary.nestingWarnings += warnNestingClamps(
+            {
+              id: componentId,
+              options: registration.options,
+              tags: outcome.resolvedTags ?? [],
+            },
+            outcome.nested,
+            warnedPairs,
+            log
+          );
+
           // Once param-dependent is confirmed, emit directly instead of
           // buffering — no need to hold bytes in memory (TIM-1179).
           if (pending.anyParamRead) {