@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/plugins/prebuilt.ts

@@ -0,0 +1,655 @@
+/**
+ * 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 type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+import type { SegmentNode } from '../routing/types.ts';
+import {
+  CACHE_MODULE_SOURCES,
+  findImportBindings,
+  generateStableCallsiteId,
+} from './callsite-ast.ts';
+import { collectJsxUsages, recordCallSiteProps } from './callsite-jsx.ts';
+import { mayPrerender, unwrapExpression } from './prebuilt-options-analysis.ts';
+import { cleanPrebuiltDir, runPrebuiltCapture } from './prebuilt-capture.ts';
+import type {
+  CallExpressionNode,
+  IdentifierNode,
+  ImportBindings,
+  MemberExpressionNode,
+  PositionedNode,
+  ProgramNode,
+} from './callsite-ast.ts';
+
+/**
+ * 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;
+}
+
+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;
+}
+
+// Sentinel key for default-export component IDs in the binding map.
+// Uses \0 prefix so it can never collide with a real JS export name
+// (TIM-1187: 'Component'/'default' leaked into the named-import namespace).
+const DEFAULT_SENTINEL = '\0default';
+
+async function collectCrossModuleProps(
+  ctx: PluginContext,
+  moduleId: string,
+  getInfo: (id: string) => PrebuiltModuleInfo | null,
+  resolve: (source: string, importer: string) => Promise<string | null>
+): Promise<void> {
+  const bindingNames = ctx.prebuiltBindingNames!;
+
+  const info = getInfo(moduleId);
+  if (!info) return;
+
+  const declaringImports = info.importedIds.filter((id) => bindingNames.has(id) && id !== moduleId);
+  if (declaringImports.length === 0) return;
+
+  // Collect exported binding names from reachable declaring modules.
+  // Skip sentinel keys — they are per-module and handled in the default
+  // import branch below. Only real export names go into the merged map.
+  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 (name === DEFAULT_SENTINEL) continue;
+      if (exportNameToId.has(name)) collisions.add(name);
+      exportNameToId.set(name, compId);
+    }
+  }
+  for (const name of collisions) exportNameToId.delete(name);
+
+  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 = ctx.parseCached!.parse(source);
+  } catch {
+    return;
+  }
+
+  const declaringSet = new Set(declaringImports);
+  const localToComponentId = new Map<string, string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ImportDeclaration') continue;
+    const importDecl = stmt as unknown as {
+      source: { value: string };
+      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;
+        // `import { default as X }` is parsed as an ImportSpecifier
+        // with imported.name === 'default' — route through the same
+        // per-source sentinel lookup as ImportDefaultSpecifier.
+        if (exportedName === 'default') {
+          const resolvedId = await resolve(importDecl.source.value, moduleId);
+          if (resolvedId && declaringSet.has(resolvedId)) {
+            const map = bindingNames.get(resolvedId)!;
+            const compId = map.get(DEFAULT_SENTINEL);
+            if (compId) localToComponentId.set(spec.local.name, compId);
+          }
+        } else {
+          const compId = exportNameToId.get(exportedName);
+          if (compId) localToComponentId.set(spec.local.name, compId);
+        }
+      } else if (spec.type === 'ImportDefaultSpecifier') {
+        const resolvedId = await resolve(importDecl.source.value, moduleId);
+        if (resolvedId && declaringSet.has(resolvedId)) {
+          const map = bindingNames.get(resolvedId)!;
+          const compId = map.get(DEFAULT_SENTINEL);
+          if (compId) localToComponentId.set(spec.local.name, compId);
+        }
+      }
+    }
+  }
+  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 = ctx.parseCached!.parse(code);
+      } 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, stmt, displayName } of callSites) {
+          if (!ctx.dev && mayPrerender(call)) {
+            const compId = componentIds[componentIdIdx++];
+            // Direct `export default cache.component(...)` produces
+            // displayName 'Component' from an ExportDefaultDeclaration —
+            // a synthetic name, not a real export. Store only the sentinel
+            // key. A variable literally named `Component` (from a
+            // VariableDeclarator) is a real binding and stored as-is.
+            if (stmt.type === 'ExportDefaultDeclaration') {
+              bindingMap.set(DEFAULT_SENTINEL, compId);
+            } else {
+              bindingMap.set(displayName, compId);
+            }
+          }
+        }
+        // Detect default re-exports that reference a declared binding
+        // and add a sentinel alias so cross-module default imports can
+        // resolve the component ID. Handles both `export default X` and
+        // `export { X as default }` (TIM-1189).
+        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_SENTINEL)) {
+              bindingMap.set(DEFAULT_SENTINEL, bindingMap.get(name)!);
+            }
+          }
+          if (stmt.type === 'ExportNamedDeclaration' && Array.isArray(stmt.specifiers)) {
+            for (const spec of stmt.specifiers as Array<{
+              local: IdentifierNode;
+              exported: IdentifierNode;
+            }>) {
+              if (spec.exported.name === 'default') {
+                const compId = bindingMap.get(spec.local.name);
+                if (compId && !bindingMap.has(DEFAULT_SENTINEL)) {
+                  bindingMap.set(DEFAULT_SENTINEL, compId);
+                }
+              }
+            }
+          }
+        }
+
+        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).
+        // Exclude sentinel keys — they are not real JSX element names.
+        const declaredBindings = new Set(
+          [...bindingMap.keys()].filter((k) => k !== DEFAULT_SENTINEL)
+        );
+        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.
+     */
+    async generateBundle(
+      _options?: unknown,
+      bundle?: Record<
+        string,
+        { type: string; modules?: Record<string, unknown>; fileName?: string }
+      >
+    ) {
+      if (ctx.dev) return;
+      if (this?.environment?.name !== 'rsc') return;
+      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;
+        resolve?: (
+          source: string,
+          importer: string,
+          opts?: unknown
+        ) => Promise<{ id: string } | null>;
+      };
+      const getInfo = (id: string) => self.getModuleInfo?.(id) ?? null;
+      const resolveFn = async (source: string, importer: string): Promise<string | null> => {
+        const result = await self.resolve?.(source, importer);
+        return result?.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);
+                await collectCrossModuleProps(ctx, modId, getInfo, resolveFn);
+              }
+              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);
+      },
+    },
+  };
+}