@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.150

package/src/plugins/adapter-build.ts

@@ -16,8 +16,10 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
-import type { PluginContext } from '#/index.js';
-import type { TimberPlatformAdapter, TimberConfig } from '#/adapters/types.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
+import type { BuildManifest } from '../server/build-manifest.js';
+import { swallow } from '../server/logger.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -35,7 +37,20 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
         const adapter = ctx.config.adapter as TimberPlatformAdapter | undefined;
         if (!adapter || typeof adapter.buildOutput !== 'function') return;
 
-        const buildDir = join(ctx.root, 'dist');
+        const buildDir = ctx.buildDir;
+
+        // Merge per-route CSS and client reference JS from the RSC plugin's
+        // assets manifest into the build manifest. This data enables
+        // <link rel="stylesheet"> and <link rel="modulepreload"> tags in
+        // <head> for server component routes (TIM-1014).
+        if (ctx.buildManifest) {
+          await mergeRscAssetsManifest(
+            buildDir,
+            ctx.root,
+            ctx.buildManifest,
+            ctx.routeClientRefKeys
+          );
+        }
 
         // Serialize the build manifest as a JS module that sets the global.
         // The adapter writes this as _timber-manifest-init.mjs and imports it
@@ -50,6 +65,12 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
             : ctx.buildManifest;
           const json = JSON.stringify(manifest);
           manifestInit = `globalThis.__TIMBER_BUILD_MANIFEST__ = ${json};\n`;
+
+          // Embed the deployment ID for version skew detection (TIM-446).
+          // The server reads this at startup via setDeploymentId().
+          if (ctx.deploymentId) {
+            manifestInit += `globalThis.__TIMBER_DEPLOYMENT_ID__ = ${JSON.stringify(ctx.deploymentId)};\n`;
+          }
         }
 
         // Strip JS from the RSC plugin's assets manifest when client JS
@@ -81,6 +102,78 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
  * intercept them. This rewrites the files on disk after all builds
  * complete but before the adapter copies them to the output directory.
  */
+/**
+ * Read the RSC plugin's assets manifest and merge per-route CSS and
+ * per-route JS modulepreloads into the build manifest.
+ *
+ * CSS: `serverResources` maps server component paths to CSS URLs.
+ * JS: `clientReferenceDeps` maps reference hashes to JS dep URLs.
+ *     Combined with `routeClientRefKeys` (from the RSC generateBundle
+ *     module graph walk) to produce per-route modulepreload entries.
+ */
+export async function mergeRscAssetsManifest(
+  buildDir: string,
+  root: string,
+  buildManifest: BuildManifest,
+  routeClientRefKeys?: Map<string, Set<string>>
+): Promise<void> {
+  const manifestPath = join(buildDir, 'rsc', '__vite_rsc_assets_manifest.js');
+  let content: string;
+  try {
+    content = await readFile(manifestPath, 'utf-8');
+  } catch {
+    return;
+  }
+
+  const jsonStr = content.replace(/^export default\s*/, '').replace(/;?\s*$/, '');
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(jsonStr);
+  } catch {
+    return;
+  }
+
+  // Merge serverResources CSS into buildManifest.css.
+  // Keys in serverResources are root-relative (e.g., "app/layout.tsx" or
+  // "src/app/layout.tsx"). Convert to absolute paths to match the runtime
+  // route manifest's filePath values.
+  const serverResources = manifest.serverResources as
+    | Record<string, { js: string[]; css: string[] }>
+    | undefined;
+  if (serverResources) {
+    for (const [relativePath, deps] of Object.entries(serverResources)) {
+      if (deps.css && deps.css.length > 0) {
+        const absolutePath = join(root, relativePath);
+        buildManifest.css[absolutePath] = deps.css;
+      }
+    }
+  }
+
+  // Build per-route modulepreload entries from routeClientRefKeys +
+  // clientReferenceDeps. Each route file's transitive client reference
+  // keys (captured during RSC generateBundle) are mapped to their JS
+  // chunk URLs via clientReferenceDeps.
+  if (routeClientRefKeys && routeClientRefKeys.size > 0) {
+    const clientReferenceDeps = manifest.clientReferenceDeps as
+      | Record<string, { js: string[]; css: string[] }>
+      | undefined;
+    if (clientReferenceDeps) {
+      for (const [filePath, refKeys] of routeClientRefKeys) {
+        const jsUrls = new Set<string>();
+        for (const key of refKeys) {
+          const deps = clientReferenceDeps[key];
+          if (deps?.js) {
+            for (const url of deps.js) jsUrls.add(url);
+          }
+        }
+        if (jsUrls.size > 0) {
+          buildManifest.modulepreload[filePath] = Array.from(jsUrls);
+        }
+      }
+    }
+  }
+}
+
 async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
   const manifestName = '__vite_rsc_assets_manifest.js';
   const paths = [join(buildDir, 'rsc', manifestName), join(buildDir, 'ssr', manifestName)];
@@ -97,7 +190,8 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
     let manifest: Record<string, unknown>;
     try {
       manifest = JSON.parse(jsonStr);
-    } catch {
+    } catch (err) {
+      swallow(err, `corrupted RSC assets manifest: ${path}`, { level: 'warn' });
       continue;
     }
 

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.js';
+import type { BuildManifest } from '../server/build-manifest.js';
+import type { SegmentNode, RouteFile } from '../routing/types.js';
+import { isDynamicMetadataExtension } from '../server/metadata-routes.js';
 
 // 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,10 +216,123 @@ 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 = '/';
@@ -242,6 +344,16 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
     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) {
@@ -267,7 +379,7 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
           '// Auto-generated build manifest — do not edit.',
           '// Dev mode: empty manifest (Vite HMR handles CSS/JS).',
           '',
-          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {} };',
           '',
           'export default manifest;',
         ].join('\n');
@@ -281,7 +393,7 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
         '// Auto-generated build manifest — do not edit.',
         '// Production: reads manifest from globalThis (set by _timber-manifest-init.js).',
         '',
-        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {} };',
         '',
         'export default manifest;',
       ].join('\n');
@@ -295,9 +407,42 @@ 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 adapter-build post hook 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);
 
+        // Compute cache-busting hashes for metadata route files
+        if (ctx.routeTree) {
+          ctx.buildManifest.metadataRouteHashes = computeMetadataRouteHashes(ctx.routeTree.root);
+        }
+
         // 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.

package/src/plugins/build-report.ts

@@ -15,9 +15,10 @@
 
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
+import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────
 
@@ -83,33 +84,23 @@ interface RouteInfo {
 /**
  * Walk the route tree and collect all leaf routes (pages + API endpoints).
  *
- * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
- * they render alongside the parent page at the same URL and are not
- * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+ * (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+ * alongside the parent page at the same URL and are not separately
+ * URL-addressable. Their JS is captured in shared/layout chunks.
  *
  * After collection, entries are deduplicated by URL path so that overlapping
  * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
- * appear once. The entry with the largest route-specific size wins.
+ * appear once. The entry with the longest segment chain (most specific
+ * match) wins.
  */
 export function collectRoutes(tree: RouteTree): RouteInfo[] {
-  const routes: RouteInfo[] = [];
-
-  function walk(node: SegmentNode, chain: SegmentNode[]): void {
-    const currentChain = [...chain, node];
-    const path = node.urlPath || '/';
-
-    if (node.page) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.page.filePath });
-    }
-    if (node.route) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.route.filePath });
-    }
-
-    // Recurse into child segments only — skip parallel slots (node.slots)
-    for (const child of node.children) walk(child, currentChain);
-  }
-
-  walk(tree.root, []);
+  const leaves = collectLeafRoutes(tree.root);
+  const routes: RouteInfo[] = leaves.map((leaf) => ({
+    path: leaf.urlPath,
+    segments: leaf.segments,
+    entryFilePath: leaf.page?.filePath ?? leaf.route?.filePath ?? null,
+  }));
 
   // Deduplicate entries with the same URL path (e.g. from overlapping route groups).
   // Keep the entry with the longest segment chain (most specific match).