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

package/src/plugins/prebuilt.ts

@@ -0,0 +1,700 @@
+/**
+ * timber-prebuilt — Vite plugin that detects `cache.component(...)` call
+ * sites and rewrites them to `__prebuilt(stableId, component, options)`.
+ *
+ * `timber.cache.component(Component, { prerender: true })` is a build-time
+ * transform, not a runtime function (design/44-render-at-build-time.md
+ * §Registration, surface API renamed by design/45-cache-lifetimes.md). The
+ * rewrite registers the component in the server-side prebuilt registry under
+ * a stable ID that keys its cached flight payloads.
+ *
+ * Detected callsite forms (mirrors timber-cache-transform, TIM-1054):
+ *   - named imports, including aliases:
+ *       `import { cache } from '@timber-js/app/cache'` + `cache.component(fn, opts)`
+ *   - namespace imports:
+ *       `import * as timber` + `timber.cache.component(fn, opts)`
+ * Computed access (`cache['component']`) is deliberately not matched — the
+ * untransformed call reaches the runtime `cache.component` fallback
+ * (cache/cache-api.ts), which warns once and renders dynamically.
+ *
+ * Matching is an ALLOWLIST of module-scope positions: the direct initializer
+ * of a top-level variable declarator (including exported ones) and a
+ * top-level `export default cache.component(...)`, with TS expression
+ * wrappers (`as`, `satisfies`, `!`) unwrapped. Nothing else is walked — no
+ * function/class/loop bodies, no params, no call arguments. Two reasons:
+ * (1) `__prebuilt` must register exactly once at module load time; the
+ * post-build capture pass walks the registry after loading modules, so a
+ * call inside a function registers too late to ever be prebuilt, and a call
+ * in a loop would re-register per iteration. (2) Name-based callee matching
+ * is only shadow-proof in these positions — nested scopes can rebind `cache`
+ * (`function render(cache) {...}`, `for (const cache of caches) ...`), and
+ * rewriting those would corrupt user code; a top-level declarator initializer
+ * cannot see a shadow of an import binding (redeclaration error). Calls in
+ * other positions fall back to the runtime path like other untraceable forms.
+ *
+ * The rewrite per mode:
+ *   production:  cache.component(fn, opts)  →  __prebuilt("<id>", fn, opts)
+ *   dev:         cache.component(fn, opts)  →  __prebuiltDev("<name>", fn, opts)
+ *
+ * with `import { __prebuilt } from '#server-internal'` prepended. In dev the
+ * wrapper is a no-op that logs once per component and renders dynamically —
+ * no caching, no markers (design/44 §Dev Mode).
+ *
+ * Component identity: `<name>_<hash16>`, e.g. `blogbody_a1b2c3d4e5f6a7b8`.
+ * The name prefix is the declaring variable's name (lowercased, for legible
+ * manifest keys and log lines); the hash is the same content-derived callsite
+ * scheme as the data cache transform (callsite-ast.ts) — deterministic across
+ * builds for unchanged calls, immune to inserting/reordering other calls, and
+ * fresh when the component or its options change. Component cache entries are
+ * per-deploy (design/45 §Per-deploy namespacing) so cross-deploy ID reuse is
+ * not a poisoning vector, but content-derived IDs keep prebuilt artifacts
+ * addressable across incremental edits for free.
+ *
+ * The transform is skipped in the client environment: server components never
+ * execute there, and `#server-internal` resolves to an empty stub in the
+ * client bundle (plugins/shims.ts).
+ *
+ * See TIM-1118, design/44-render-at-build-time.md, design/45-cache-lifetimes.md.
+ */
+
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import MagicString from 'magic-string';
+import { parseAst } from 'vite';
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+import type { SegmentNode } from '../routing/types.js';
+import {
+  CACHE_MODULE_SOURCES,
+  findImportBindings,
+  generateStableCallsiteId,
+} from './callsite-ast.js';
+import { collectJsxUsages, recordCallSiteProps } from './callsite-jsx.js';
+import { cleanPrebuiltDir, runPrebuiltCapture } from './prebuilt-capture.js';
+import type {
+  CallExpressionNode,
+  IdentifierNode,
+  ImportBindings,
+  MemberExpressionNode,
+  PositionedNode,
+  ProgramNode,
+} from './callsite-ast.js';
+
+/**
+ * Is this callee `cache.component` (named import, aliases included) or
+ * `ns.cache.component` (namespace import)? Computed access is not matched.
+ */
+function isCacheComponentCallee(callee: PositionedNode, bindings: ImportBindings): boolean {
+  if (callee.type !== 'MemberExpression') return false;
+  const member = callee as unknown as MemberExpressionNode;
+  if (
+    member.computed ||
+    member.property.type !== 'Identifier' ||
+    (member.property as IdentifierNode).name !== 'component'
+  ) {
+    return false;
+  }
+  // cache.component — object is a named-import binding of `cache`
+  if (member.object.type === 'Identifier') {
+    return bindings.named.has((member.object as IdentifierNode).name);
+  }
+  // ns.cache.component — object is `ns.cache` on a namespace import
+  if (member.object.type === 'MemberExpression') {
+    const inner = member.object as unknown as MemberExpressionNode;
+    return (
+      !inner.computed &&
+      inner.object.type === 'Identifier' &&
+      bindings.namespaces.has((inner.object as IdentifierNode).name) &&
+      inner.property.type === 'Identifier' &&
+      (inner.property as IdentifierNode).name === 'cache'
+    );
+  }
+  return false;
+}
+
+interface VariableDeclaratorNode extends PositionedNode {
+  type: 'VariableDeclarator';
+  id: PositionedNode;
+  init?: PositionedNode | null;
+}
+
+/**
+ * Offset where an injected import may be inserted: after the directive
+ * prologue ('use server', 'use strict', ...). Prepending at offset 0 would
+ * demote a leading directive to a plain expression statement — silently
+ * disabling it.
+ */
+function importInsertionOffset(program: ProgramNode): number {
+  for (const stmt of program.body) {
+    const isDirective =
+      stmt.type === 'ExpressionStatement' &&
+      typeof (stmt as { directive?: unknown }).directive === 'string';
+    if (!isDirective) return stmt.start;
+  }
+  // All statements are directives — no call sites can exist, but be safe.
+  return program.body.length > 0 ? program.body[program.body.length - 1].end : 0;
+}
+
+/** TS/paren wrappers that may sit between a declarator and the call. */
+const EXPRESSION_WRAPPER_TYPES = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'ParenthesizedExpression',
+]);
+
+function unwrapExpression(node: PositionedNode): PositionedNode {
+  let current = node;
+  while (EXPRESSION_WRAPPER_TYPES.has(current.type) && current.expression) {
+    current = current.expression as PositionedNode;
+  }
+  return current;
+}
+
+interface ObjectPropertyNode extends PositionedNode {
+  type: 'Property';
+  computed?: boolean;
+  key: PositionedNode & { name?: string; value?: unknown };
+  value: PositionedNode & { value?: unknown };
+}
+
+/**
+ * Can this call site's options put the component in the prerender tier?
+ *
+ * Runtime-tier call sites (`ttl`/`tags` without `prerender`) must do NO
+ * build work — recording them would make the post-build hook import the
+ * built RSC entry (running production startup) and load route modules for
+ * routes that have nothing to prerender (codex P2 on PR #836). The answer
+ * is static only when the options argument is an object literal:
+ *
+ *   - literal with `prerender: true`            → yes
+ *   - literal with `prerender: false`/absent    → no  (spread-free)
+ *   - anything else (identifier, spread, non-literal `prerender` value)
+ *     → conservatively yes — the capture pass re-checks the real options
+ *       at runtime and skips non-prerender registrations; over-inclusion
+ *       costs a wasted entry load, under-inclusion would silently skip
+ *       prerendering.
+ */
+function mayPrerender(call: CallExpressionNode): boolean {
+  if (call.arguments.length < 2) return false; // no options → no lifetime → never prerender
+  const options = unwrapExpression(call.arguments[1] as PositionedNode);
+  if (options.type !== 'ObjectExpression') return true;
+  const properties = (options as unknown as { properties: PositionedNode[] }).properties ?? [];
+  // Walk in source order with last-write-wins, mirroring object-literal
+  // evaluation: `{ prerender: false, ...opts }` may end up prerenderable
+  // (the spread can override), while `{ ...opts, prerender: false }`
+  // is statically false (codex P2 on PR #836). Computed keys are treated
+  // like spreads — they may evaluate to 'prerender'.
+  type Verdict = 'absent' | 'true' | 'false' | 'unknown';
+  let verdict: Verdict = 'absent';
+  for (const prop of properties) {
+    if (prop.type === 'SpreadElement') {
+      verdict = 'unknown';
+      continue;
+    }
+    if (prop.type !== 'Property') continue;
+    const property = prop as ObjectPropertyNode;
+    if (property.computed) {
+      verdict = 'unknown';
+      continue;
+    }
+    const keyName =
+      property.key.type === 'Identifier'
+        ? property.key.name
+        : property.key.type === 'Literal'
+          ? String(property.key.value)
+          : undefined;
+    if (keyName !== 'prerender') continue;
+    const value = unwrapExpression(property.value);
+    if (value.type === 'Literal') {
+      verdict = (value as { value?: unknown }).value === true ? 'true' : 'false';
+    } else {
+      verdict = 'unknown'; // `prerender: flag` — not statically known
+    }
+  }
+  return verdict === 'true' || verdict === 'unknown';
+}
+
+interface CandidateSite {
+  call: CallExpressionNode;
+  stmt: PositionedNode;
+  displayName: string;
+}
+
+/**
+ * Collect matching call sites from the allowlisted module-scope positions:
+ * top-level (possibly exported) variable declarator initializers and
+ * `export default` expressions. Returned in source order. The display name
+ * is the declaring variable's name, or 'Component' for default exports.
+ */
+function collectModuleScopeSites(program: ProgramNode, bindings: ImportBindings): CandidateSite[] {
+  const isMatch = (node: PositionedNode): node is CallExpressionNode =>
+    node.type === 'CallExpression' &&
+    (node as unknown as CallExpressionNode).arguments.length >= 1 &&
+    (node as unknown as CallExpressionNode).arguments.length <= 2 &&
+    isCacheComponentCallee((node as unknown as CallExpressionNode).callee, bindings);
+
+  const sites: CandidateSite[] = [];
+  for (const stmt of program.body) {
+    if (stmt.type === 'ExportDefaultDeclaration' && stmt.declaration) {
+      const call = unwrapExpression(stmt.declaration as PositionedNode);
+      if (isMatch(call)) sites.push({ call, stmt, displayName: 'Component' });
+      continue;
+    }
+    let decl = stmt;
+    if (stmt.type === 'ExportNamedDeclaration' && stmt.declaration) {
+      decl = stmt.declaration as PositionedNode;
+    }
+    if (decl.type !== 'VariableDeclaration' || !Array.isArray(decl.declarations)) continue;
+    for (const d of decl.declarations as VariableDeclaratorNode[]) {
+      if (!d.init) continue;
+      const call = unwrapExpression(d.init as PositionedNode);
+      if (!isMatch(call)) continue;
+      const displayName = d.id.type === 'Identifier' ? (d.id as IdentifierNode).name : 'Component';
+      sites.push({ call, stmt, displayName });
+    }
+  }
+  return sites;
+}
+
+/**
+ * Generate the stable component ID for a cache.component() call site:
+ * `<sanitized-name>_<content-hash16>`. Exported for testing.
+ */
+export function generatePrebuiltId(
+  relativeModulePath: string,
+  statementText: string,
+  callSpanText: string,
+  occurrence: number,
+  displayName: string
+): string {
+  const prefix = displayName.toLowerCase().replace(/[^a-z0-9]/g, '') || 'component';
+  const hash = generateStableCallsiteId(
+    relativeModulePath,
+    'component',
+    statementText,
+    callSpanText,
+    occurrence
+  );
+  return `${prefix}_${hash}`;
+}
+
+// ─── Route → component attribution (module-graph walk) ────────────────────
+
+/** Rollup getModuleInfo shape (subset — static + dynamic imports). */
+export interface PrebuiltModuleInfo {
+  importedIds: string[];
+  dynamicallyImportedIds?: string[];
+}
+
+/**
+ * Collect the prebuilt component IDs transitively reachable from a route
+ * file, following static AND dynamic imports. Same pattern as the
+ * client-reference walk in build-manifest.ts; dynamic imports are included
+ * because a dynamically-imported module still registers its components
+ * when it eventually loads — attribution over-approximating registration
+ * is handled at capture time (an attributed-but-unregistered component is
+ * reported and skipped).
+ */
+export function collectReachablePrebuiltComponents(
+  entryModuleId: string,
+  moduleComponents: Map<string, string[]>,
+  getModuleInfo: (id: string) => PrebuiltModuleInfo | null
+): string[] {
+  const visited = new Set<string>();
+  const result = new Set<string>();
+  const stack = [entryModuleId];
+  while (stack.length > 0) {
+    const moduleId = stack.pop()!;
+    if (visited.has(moduleId)) continue;
+    visited.add(moduleId);
+    const ids = moduleComponents.get(moduleId);
+    if (ids) for (const id of ids) result.add(id);
+    const info = getModuleInfo(moduleId);
+    if (!info) continue;
+    for (const imported of info.importedIds) stack.push(imported);
+    for (const imported of info.dynamicallyImportedIds ?? []) stack.push(imported);
+  }
+  return Array.from(result);
+}
+
+/**
+ * Collect page and layout file paths from the scanned route tree — the
+ * walk roots for attribution. Slots and intercepting/private segments are
+ * excluded, mirroring the capture pass's route walk
+ * (server/prebuilt-builder.ts §collectCandidateRoutes).
+ */
+function collectPageAndLayoutFiles(root: SegmentNode): string[] {
+  const files: string[] = [];
+  const walk = (node: SegmentNode) => {
+    if (node.segmentType === 'intercepting' || node.segmentType === 'private') return;
+    if (node.page) files.push(node.page.filePath);
+    if (node.layout) files.push(node.layout.filePath);
+    for (const child of node.children) walk(child);
+  };
+  walk(root);
+  return files;
+}
+
+/**
+ * For a route file (page/layout), check if it imports from any prebuilt-
+ * declaring module and extract JSX call-site props for those bindings.
+ * Uses `getModuleInfo` to get the RESOLVED import targets and the module's
+ * transformed code (available on Rollup's ModuleInfo at generateBundle).
+ */
+function collectCrossModuleProps(
+  ctx: PluginContext,
+  moduleId: string,
+  getInfo: (id: string) => PrebuiltModuleInfo | null
+): void {
+  const bindingNames = ctx.prebuiltBindingNames!;
+
+  const info = getInfo(moduleId);
+  if (!info) return;
+
+  // Which of this module's imports are prebuilt-declaring modules?
+  // Exclude self — same-module usages are already captured in the transform.
+  const declaringImports = info.importedIds.filter((id) => bindingNames.has(id) && id !== moduleId);
+  if (declaringImports.length === 0) return;
+
+  // Collect exported binding names from reachable declaring modules.
+  // On collision (two declaring modules export the same name) drop the
+  // entry — we can't tell which import it came from without resolving the
+  // raw specifier, and a wrong match would produce spurious cache entries.
+  const exportNameToId = new Map<string, string>();
+  const collisions = new Set<string>();
+  for (const declId of declaringImports) {
+    const map = bindingNames.get(declId)!;
+    for (const [name, compId] of map) {
+      if (exportNameToId.has(name)) collisions.add(name);
+      exportNameToId.set(name, compId);
+    }
+  }
+  for (const name of collisions) exportNameToId.delete(name);
+
+  // Read the route file source. getModuleInfo may provide `code` on
+  // Vite's extended Rollup interface; fall back to reading from disk.
+  let source: string | null = null;
+  const extInfo = getInfo(moduleId) as unknown as { code?: string | null };
+  if (extInfo && typeof extInfo.code === 'string') {
+    source = extInfo.code;
+  } else {
+    try {
+      source = readFileSync(moduleId, 'utf8');
+    } catch {
+      return;
+    }
+  }
+  if (!source) return;
+
+  let program: ProgramNode;
+  try {
+    program = parseAst(source, { lang: 'tsx' }) as unknown as ProgramNode;
+  } catch {
+    return;
+  }
+
+  // Build local-name → componentId by matching import specifiers against
+  // the known exported binding names from declaring modules.
+  const localToComponentId = new Map<string, string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ImportDeclaration') continue;
+    const importDecl = stmt as unknown as {
+      specifiers: Array<{
+        type: string;
+        local: { name: string };
+        imported?: { name: string };
+      }>;
+    };
+    for (const spec of importDecl.specifiers) {
+      if (spec.type === 'ImportSpecifier') {
+        const exportedName = spec.imported?.name ?? spec.local.name;
+        const compId = exportNameToId.get(exportedName);
+        if (compId) localToComponentId.set(spec.local.name, compId);
+      } else if (spec.type === 'ImportDefaultSpecifier') {
+        // Default exports may be declared as `export default cache.component(...)`
+        // (recorded as 'Component') or `const X = cache.component(...); export default X`
+        // (recorded under the variable name 'X'). When the declaring module has
+        // exactly one prebuilt binding, a default import unambiguously refers to it.
+        const compId = exportNameToId.get('Component') ?? exportNameToId.get('default');
+        if (compId) {
+          localToComponentId.set(spec.local.name, compId);
+        } else if (exportNameToId.size === 1) {
+          const [, soleId] = [...exportNameToId.entries()][0];
+          localToComponentId.set(spec.local.name, soleId);
+        }
+      }
+    }
+  }
+  if (localToComponentId.size === 0) return;
+
+  const usages = collectJsxUsages(program, new Set(localToComponentId.keys()));
+  for (const [localName, propsList] of usages) {
+    const componentId = localToComponentId.get(localName);
+    if (!componentId) continue;
+    for (const props of propsList) {
+      if (props === null) continue;
+      recordCallSiteProps(ctx, componentId, props);
+    }
+  }
+}
+
+export function timberPrebuilt(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-prebuilt',
+
+    transform(code, id) {
+      // Drop this module's stale attribution first — in a long-lived
+      // `vite build --watch` process the plugin context outlives builds,
+      // and an edit that removes a module's prerender call sites must
+      // remove its recorded IDs even when this transform exits early
+      // below (codex P2 on PR #836). Re-recorded at the bottom if the
+      // edited module still has prerender-capable call sites.
+      if (!ctx.dev && this?.environment?.name === 'rsc') {
+        ctx.prebuiltModuleComponents?.delete(id);
+      }
+      if (!code.includes('@timber-js/app/cache') && !code.includes('timber/cache')) return;
+      // Skip node_modules (don't transform third-party code)
+      if (id.includes('node_modules')) return;
+      // Skip the client environment — server components never execute there
+      // and #server-internal resolves to an empty stub.
+      if (this?.environment?.name === 'client') return;
+
+      let program: ProgramNode;
+      try {
+        program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+      } catch {
+        return;
+      }
+
+      const bindings = findImportBindings(program, CACHE_MODULE_SOURCES, 'cache');
+      if (bindings.named.size === 0 && bindings.namespaces.size === 0) return;
+
+      // Allowlisted module-scope positions only — each site carries its
+      // enclosing statement's source text (into the ID hash) and the
+      // declaring variable's name (display name). Already in source order.
+      const callSites = collectModuleScopeSites(program, bindings);
+      if (callSites.length === 0) return;
+
+      const root = ctx.root || process.cwd();
+      const relPath = relative(root, id);
+      const s = new MagicString(code);
+      const occurrences = new Map<string, number>();
+      const wrapperName = ctx.dev ? '__prebuiltDev' : '__prebuilt';
+      const componentIds: string[] = [];
+
+      for (const { call, stmt, displayName } of callSites) {
+        const stmtText = code.slice(stmt.start, stmt.end);
+        const spanText = code.slice(call.start, call.end);
+        // Byte-identical (statement, call) pairs are only possible via `var`
+        // redeclaration; the occurrence index keeps their IDs distinct.
+        const dupKey = stmtText + String.fromCharCode(0) + spanText;
+        const occurrence = occurrences.get(dupKey) ?? 0;
+        occurrences.set(dupKey, occurrence + 1);
+
+        // Production gets the stable ID (keys build artifacts and cache
+        // entries); dev gets the display name (only used for the one-time
+        // "rendering dynamically" log).
+        const firstArg = ctx.dev
+          ? displayName
+          : generatePrebuiltId(relPath, stmtText, spanText, occurrence, displayName);
+        // Only prerender-capable call sites feed the capture attribution —
+        // runtime-tier components (ttl/tags only) must do no build work.
+        if (!ctx.dev && mayPrerender(call)) componentIds.push(firstArg);
+
+        s.overwrite(call.callee.start, call.callee.end, wrapperName);
+        s.appendLeft(call.arguments[0].start, `${JSON.stringify(firstArg)}, `);
+      }
+
+      // Record this module's component IDs for the RSC generateBundle
+      // module-graph walk (route → component attribution, TIM-1119).
+      if (!ctx.dev && componentIds.length > 0 && this?.environment?.name === 'rsc') {
+        ctx.prebuiltModuleComponents ??= new Map();
+        ctx.prebuiltModuleComponents.set(id, componentIds);
+
+        // Record binding name → component ID mapping for cross-module
+        // prop detection at generateBundle time (TIM-1142).
+        const bindingMap = new Map<string, string>();
+        let componentIdIdx = 0;
+        for (const { call, displayName } of callSites) {
+          if (!ctx.dev && mayPrerender(call)) {
+            bindingMap.set(displayName, componentIds[componentIdIdx++]);
+          }
+        }
+        // Detect `export default <identifier>` re-exports that reference
+        // a declared binding and add a 'default' alias so cross-module
+        // default imports can resolve the component ID.
+        for (const stmt of program.body) {
+          if (
+            stmt.type === 'ExportDefaultDeclaration' &&
+            stmt.declaration &&
+            (stmt.declaration as PositionedNode).type === 'Identifier'
+          ) {
+            const name = (stmt.declaration as PositionedNode as unknown as IdentifierNode).name;
+            if (bindingMap.has(name) && !bindingMap.has('default')) {
+              bindingMap.set('default', bindingMap.get(name)!);
+            }
+          }
+        }
+
+        if (bindingMap.size > 0) {
+          ctx.prebuiltBindingNames ??= new Map();
+          ctx.prebuiltBindingNames.set(id, bindingMap);
+        }
+
+        // Same-module JSX usages: if a prebuilt component is declared AND
+        // used (<BlogBody variant="full" />) in the same module, capture
+        // its static call-site props here (TIM-1142, design/44 §Props).
+        const declaredBindings = new Set(bindingMap.keys());
+        if (declaredBindings.size > 0) {
+          const usages = collectJsxUsages(program, declaredBindings);
+          for (const [bindingName, propsList] of usages) {
+            const compId = bindingMap.get(bindingName);
+            if (!compId) continue;
+            for (const props of propsList) {
+              if (props === null) {
+                // Dynamic props at this call site — warn at build time,
+                // this usage will always render live (design/44 §Props
+                // Derivation limitation).
+                continue;
+              }
+              recordCallSiteProps(ctx, compId, props);
+            }
+          }
+        }
+      }
+
+      s.appendLeft(
+        importInsertionOffset(program),
+        `import { ${wrapperName} } from '#server-internal';\n`
+      );
+
+      return {
+        code: s.toString(),
+        map: s.generateMap({ hires: 'boundary' }),
+      };
+    },
+
+    /**
+     * RSC environment, production: walk each route file's module graph to
+     * attribute prebuilt components to the routes that can render them.
+     * The graph walk (rather than load-order registry deltas) is what makes
+     * SHARED components work — a component imported by several routes is
+     * captured under every importing route's param combos.
+     */
+    generateBundle(
+      _options?: unknown,
+      bundle?: Record<
+        string,
+        { type: string; modules?: Record<string, unknown>; fileName?: string }
+      >
+    ) {
+      if (ctx.dev) return;
+      if (this?.environment?.name !== 'rsc') return;
+      // Recompute attribution from scratch every build — a stale map from
+      // a previous watch-mode build would otherwise keep scheduling the
+      // capture (and its built-entry import) for components that no
+      // longer exist (codex P2 on PR #836).
+      ctx.routePrebuiltComponents = undefined;
+      const moduleComponents = ctx.prebuiltModuleComponents;
+      if (!moduleComponents || moduleComponents.size === 0 || !ctx.routeTree) return;
+
+      const self = this as unknown as {
+        getModuleInfo?: (id: string) => PrebuiltModuleInfo | null;
+      };
+      const getInfo = (id: string) => self.getModuleInfo?.(id) ?? null;
+
+      const routeComponents = new Map<string, string[]>();
+      for (const filePath of collectPageAndLayoutFiles(ctx.routeTree.root)) {
+        const ids = collectReachablePrebuiltComponents(filePath, moduleComponents, getInfo);
+        if (ids.length > 0) routeComponents.set(filePath, ids);
+      }
+      if (routeComponents.size > 0) {
+        ctx.routePrebuiltComponents = routeComponents;
+
+        // Build a map of componentId → chunk fileName for declaring
+        // modules that aren't route files themselves (behind dynamic
+        // imports like import.meta.glob). The capture pass imports these
+        // chunks to trigger cache.component() registration.
+        if (bundle) {
+          const routeFileSet = new Set(routeComponents.keys());
+          const lazyChunks = new Map<string, string>();
+          for (const [moduleId, componentIds] of moduleComponents) {
+            if (routeFileSet.has(moduleId)) continue;
+            for (const [, chunk] of Object.entries(bundle)) {
+              if (chunk.type !== 'chunk' || !chunk.modules) continue;
+              if (moduleId in chunk.modules) {
+                for (const id of componentIds) lazyChunks.set(id, chunk.fileName!);
+                break;
+              }
+            }
+          }
+          if (lazyChunks.size > 0) ctx.prebuiltLazyChunks = lazyChunks;
+        }
+
+        // Cross-module call-site prop detection (TIM-1142): walk the
+        // module graph from each route file and scan ALL reachable modules
+        // for JSX usages of prebuilt components — not just the route files
+        // themselves. A component used in a helper (page → Shell → <BlogBody>)
+        // must have its props captured from wherever the JSX lives.
+        if (ctx.prebuiltBindingNames && ctx.prebuiltBindingNames.size > 0) {
+          const scannedModules = new Set<string>();
+          for (const filePath of routeComponents.keys()) {
+            const visited = new Set<string>();
+            const stack = [filePath];
+            while (stack.length > 0) {
+              const modId = stack.pop()!;
+              if (visited.has(modId)) continue;
+              visited.add(modId);
+              if (!scannedModules.has(modId)) {
+                scannedModules.add(modId);
+                collectCrossModuleProps(ctx, modId, getInfo);
+              }
+              const modInfo = getInfo(modId);
+              if (!modInfo) continue;
+              for (const imp of modInfo.importedIds) stack.push(imp);
+              for (const imp of modInfo.dynamicallyImportedIds ?? []) stack.push(imp);
+            }
+          }
+        }
+      } else {
+        // Call sites were transformed but none are reachable from any route
+        // file — either they live behind slots (not modeled) or the graph
+        // walk's module IDs diverged from the route tree's file paths. Say
+        // so loudly: the alternative is prerender silently doing nothing.
+        console.warn(
+          `[timber] cache.component: ${moduleComponents.size} module(s) declare prebuilt ` +
+            `components, but none are reachable from any page or layout — no payloads ` +
+            `will be prerendered`
+        );
+      }
+    },
+
+    /**
+     * Post-build capture (design/44 §Build Phase). `order: 'post'` runs
+     * after the RSC plugin's buildApp — all five build steps are complete —
+     * and BEFORE timber-adapter-build's post hook (plugin array order), so
+     * `prebuilt/` exists when the adapter assembles its output (TIM-1122).
+     */
+    buildApp: {
+      order: 'post' as const,
+      async handler() {
+        if (ctx.dev) return;
+        ctx.captureSummary = undefined;
+        // Always shed a previous build's artifacts first — even when THIS
+        // build captures nothing, a stale manifest must never ship.
+        await cleanPrebuiltDir(ctx.buildDir);
+        if (!ctx.routePrebuiltComponents || ctx.routePrebuiltComponents.size === 0) return;
+        if (ctx.config.output === 'static') {
+          // design/44 §output: 'static' — everything already renders at
+          // build time there; the wrapper is a no-op, not an error.
+          console.log(
+            `[timber] cache.component: skipped prerender capture (output: 'static' renders all components at build time)`
+          );
+          return;
+        }
+        ctx.captureSummary = await runPrebuiltCapture(ctx);
+      },
+    },
+  };
+}