@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/plugins/build-manifest.ts

@@ -16,9 +16,13 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 
+import { randomUUID, createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import type { Plugin, ResolvedConfig } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
+import type { PluginContext } from '../plugin-context.ts';
+import { EMPTY_BUILD_MANIFEST, type BuildManifest } from '../server/build-manifest.ts';
+import type { SegmentNode, RouteFile } from '../routing/types.ts';
+import { isDynamicMetadataExtension } from '../server/metadata-routes.ts';
 
 // Rollup types used by generateBundle hook — imported from vite which re-exports them.
 // We define minimal interfaces here to avoid a direct 'rollup' dependency.
@@ -30,6 +34,7 @@ interface OutputChunk {
   name: string;
   code: string;
   viteMetadata?: { importedCss?: Set<string> };
+  modules?: Record<string, { code: string | null; renderedLength: number }>;
 }
 
 interface OutputAsset {
@@ -83,7 +88,7 @@ export function parseViteManifest(
     modulepreload[inputPath] = collectTransitiveDeps(inputPath, viteManifest, base);
   }
 
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -180,23 +185,7 @@ export function buildManifestFromBundle(
     }
   }
 
-  // Collect ALL CSS assets from the bundle under the `_global` key.
-  // Route files (app/layout.tsx, app/page.tsx) are server components —
-  // they don't appear in the client bundle, so per-route CSS keying
-  // via facadeModuleId doesn't work. The RSC plugin handles per-route
-  // CSS injection via data-rsc-css-href. For Link headers (103 Early
-  // Hints), we emit all CSS files — they're just prefetch hints.
-  const allCss: string[] = [];
-  for (const item of Object.values(bundle) as (OutputChunk | OutputAsset)[]) {
-    if (item.type === 'asset' && item.fileName.endsWith('.css')) {
-      allCss.push(base + item.fileName);
-    }
-  }
-  if (allCss.length > 0) {
-    css['_global'] = allCss;
-  }
-
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -227,21 +216,142 @@ function collectTransitiveBundleDeps(
   return result;
 }
 
+/**
+ * Walk the route tree and compute short content hashes for metadata route files
+ * (opengraph-image, icon, apple-icon) used for cache-busting
+ * the auto-linked URLs in <head>.
+ */
+function computeMetadataRouteHashes(node: SegmentNode<RouteFile>): Record<string, string> {
+  const hashes: Record<string, string> = {};
+
+  if (node.metadataRoutes) {
+    for (const [baseName, file] of Object.entries(node.metadataRoutes)) {
+      if (!isDynamicMetadataExtension(baseName, file.extension)) {
+        // For static files, hash the file content
+        try {
+          const content = readFileSync(file.filePath);
+          const hash = createHash('sha256').update(content).digest('hex').slice(0, 8);
+          hashes[file.filePath] = hash;
+        } catch {
+          // File unreadable — skip hash, DEV_NONCE fallback applies
+        }
+      } else {
+        // For dynamic files (.ts/.tsx), hash the source file as a reasonable
+        // approximation — the output depends on runtime data too, but the
+        // source change is the best build-time signal we have.
+        try {
+          const content = readFileSync(file.filePath);
+          const hash = createHash('sha256').update(content).digest('hex').slice(0, 8);
+          hashes[file.filePath] = hash;
+        } catch {
+          // File unreadable — skip
+        }
+      }
+    }
+  }
+
+  for (const child of node.children) {
+    Object.assign(hashes, computeMetadataRouteHashes(child));
+  }
+  for (const slot of Object.values(node.slots)) {
+    Object.assign(hashes, computeMetadataRouteHashes(slot));
+  }
+
+  return hashes;
+}
+
+// Regex to extract client reference hash keys from registerClientReference calls.
+// Matches: registerClientReference(..., "abc123def456", "ExportName")
+const CLIENT_REF_KEY_RE = /registerClientReference\([^,]+,\s*"([0-9a-f]{12})"/g;
+
+/**
+ * Collect all route file paths (layout, page) from the route tree.
+ */
+function collectRouteFilePaths(node: SegmentNode<RouteFile>): string[] {
+  const paths: string[] = [];
+  if (node.layout) paths.push(node.layout.filePath);
+  if (node.page) paths.push(node.page.filePath);
+  for (const child of node.children) paths.push(...collectRouteFilePaths(child));
+  for (const slot of Object.values(node.slots)) paths.push(...collectRouteFilePaths(slot));
+  return paths;
+}
+
+/**
+ * Scan RSC bundle chunks to find which modules contain registerClientReference
+ * calls, and extract the reference hash keys from each.
+ */
+function buildClientRefIndex(bundle: OutputBundle): Map<string, string[]> {
+  const index = new Map<string, string[]>();
+  for (const item of Object.values(bundle)) {
+    if (item.type !== 'chunk' || !item.modules) continue;
+    for (const [moduleId, mod] of Object.entries(item.modules)) {
+      if (!mod.code) continue;
+      const keys: string[] = [];
+      for (const match of mod.code.matchAll(CLIENT_REF_KEY_RE)) {
+        keys.push(match[1]);
+      }
+      if (keys.length > 0) {
+        index.set(moduleId, keys);
+      }
+    }
+  }
+  return index;
+}
+
+/** Rollup getModuleInfo shape (subset). */
+interface ModuleInfo {
+  importedIds: string[];
+}
+
+/**
+ * Walk a module's transitive imports to collect all client reference
+ * keys reachable from it.
+ */
+function walkModuleImports(
+  moduleId: string,
+  clientRefIndex: Map<string, string[]>,
+  visited: Set<string>,
+  result: Set<string>,
+  getModuleInfo: (id: string) => ModuleInfo | null
+): void {
+  if (visited.has(moduleId)) return;
+  visited.add(moduleId);
+
+  const refKeys = clientRefIndex.get(moduleId);
+  if (refKeys) {
+    for (const key of refKeys) result.add(key);
+  }
+
+  const info = getModuleInfo(moduleId);
+  if (!info) return;
+  for (const importedId of info.importedIds) {
+    walkModuleImports(importedId, clientRefIndex, visited, result, getModuleInfo);
+  }
+}
+
 /**
  * Create the timber-build-manifest Vite plugin.
  *
- * Hooks: configResolved, resolveId, load, generateBundle (client env only)
+ * Hooks: configResolved, resolveId, load, generateBundle (client and RSC envs)
  */
 export function timberBuildManifest(ctx: PluginContext): Plugin {
-  let resolvedBase = '/';
   let isDev = false;
 
   return {
     name: 'timber-build-manifest',
 
     configResolved(config: ResolvedConfig) {
-      resolvedBase = config.base;
       isDev = config.command === 'serve';
+
+      // Generate a per-build deployment ID early so virtual:timber-config
+      // can serialize it during the load hook (which runs before generateBundle).
+      // A random UUID is used instead of a content hash — determinism provides
+      // no real benefit here since you almost never redeploy identical code,
+      // and a random ID avoids the timing problem where the content hash was
+      // only available after generateBundle (TIM-452).
+      if (!isDev && !ctx.deploymentId) {
+        ctx.deploymentId = randomUUID().replace(/-/g, '').slice(0, 16);
+      }
     },
 
     resolveId(id: string) {
@@ -261,13 +371,18 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
     load(id: string) {
       if (id !== RESOLVED_VIRTUAL_ID) return null;
 
+      // Serialized, not restated: an empty manifest is described once, in
+      // server/build-manifest.ts. Both branches below emitted their own object
+      // literal and had already drifted apart — see EMPTY_BUILD_MANIFEST.
+      const empty = JSON.stringify(EMPTY_BUILD_MANIFEST);
+
       // In dev mode, return empty manifest — Vite HMR handles CSS.
       if (isDev) {
         return [
           '// Auto-generated build manifest — do not edit.',
           '// Dev mode: empty manifest (Vite HMR handles CSS/JS).',
           '',
-          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+          `const manifest = ${empty};`,
           '',
           'export default manifest;',
         ].join('\n');
@@ -277,11 +392,17 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
       // The adapter writes a _timber-manifest-init.js that sets this global
       // before the RSC handler imports this module. ESM evaluation order
       // guarantees the global is set by the time this code runs.
+      //
+      // The literal is only reached when the global is unset — an app built
+      // with no adapter, which writes no init module. It is NOT the map the
+      // build computed; that lives in _timber-manifest-init.js (TIM-1300).
       return [
         '// Auto-generated build manifest — do not edit.',
         '// Production: reads manifest from globalThis (set by _timber-manifest-init.js).',
+        '// The object below is only the fallback for when that global is unset —',
+        '// the real manifest, including the requestDep map, is in that init module.',
         '',
-        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+        `const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? ${empty};`,
         '',
         'export default manifest;',
       ].join('\n');
@@ -295,22 +416,69 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
 
       const envName = (this as { environment?: { name: string } }).environment?.name;
 
+      // RSC environment: walk the module graph to find which client
+      // references each route file transitively imports. Store the
+      // mapping in ctx so the post-build phase can cross-reference
+      // with clientReferenceDeps to populate per-route modulepreloads.
+      if (envName === 'rsc' && ctx.routeTree) {
+        const clientRefIndex = buildClientRefIndex(bundle);
+        if (clientRefIndex.size > 0) {
+          const routeFiles = collectRouteFilePaths(ctx.routeTree.root);
+          const routeClientRefKeys = new Map<string, Set<string>>();
+
+          const getInfo = (id: string) =>
+            (this as { getModuleInfo?: (id: string) => ModuleInfo | null }).getModuleInfo?.(id) ??
+            null;
+
+          for (const filePath of routeFiles) {
+            const refKeys = new Set<string>();
+            walkModuleImports(filePath, clientRefIndex, new Set(), refKeys, getInfo);
+            if (refKeys.size > 0) {
+              routeClientRefKeys.set(filePath, refKeys);
+            }
+          }
+
+          if (routeClientRefKeys.size > 0) {
+            ctx.routeClientRefKeys = routeClientRefKeys;
+          }
+        }
+      }
+
       if (envName === 'client') {
-        ctx.buildManifest = buildManifestFromBundle(bundle, resolvedBase, ctx.root);
+        ctx.buildManifest = buildManifestFromBundle(bundle, ctx.base, ctx.root);
+
+        // Compute cache-busting hashes for metadata route files
+        if (ctx.routeTree) {
+          ctx.buildManifest.metadataRouteHashes = computeMetadataRouteHashes(ctx.routeTree.root);
+        }
+
+        // Attach the static request-dependency map from the request-dep
+        // plugin, computed in the RSC `buildEnd` hook. The RSC environment is
+        // built before the client one, so the field is populated by now.
+        //
+        // Absent means the RSC `buildEnd` never ran — a broken plugin pipeline,
+        // not an app without segments, which produces `{}`. Serializing that as
+        // an empty map is indistinguishable at runtime from an analysis that
+        // found nothing (`server/request-dep.ts` answers `true` for any absent
+        // key either way), so every segment and slot silently stops being a
+        // skip candidate and slot caching is off with nothing to show for it.
+        // Fail the build instead (TIM-1300).
+        if (ctx.requestDepMap === undefined) {
+          throw new Error(
+            '[timber] Build manifest: the request-dependency map was never computed. ' +
+              "The RSC environment's buildEnd hook did not run before the client build, " +
+              'so no segment or slot could be skipped on client navigation. This is a ' +
+              'plugin pipeline bug — timber-request-dep must run in the rsc environment.'
+          );
+        }
+        ctx.buildManifest.requestDep = ctx.requestDepMap;
 
         // When client JavaScript is disabled, strip JS chunks from the bundle
         // so Rollup never writes them to disk. CSS assets are preserved —
-        // they're still needed for server-rendered HTML.
-        //
-        // This is an optimization: adapter-build.ts still strips JS from the
-        // build manifest and RSC assets manifest as a defense-in-depth fallback.
+        // they're still needed for server-rendered HTML. The JS references
+        // in the manifest are stripped once, by the post-build phase, after
+        // it has merged in everything else (plugins/post-build.ts).
         if (ctx.clientJavascript.disabled) {
-          // Clear JS and modulepreload from the manifest (they'd be stripped
-          // by adapter-build.ts anyway, but doing it here avoids the round-trip).
-          ctx.buildManifest.js = {};
-          ctx.buildManifest.modulepreload = {};
-
-          // Remove JS chunks from the Rollup bundle — prevents disk writes.
           for (const [fileName, item] of Object.entries(bundle)) {
             if (item.type === 'chunk') {
               delete bundle[fileName];