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

package/src/plugins/adapter-build.ts

@@ -15,9 +15,13 @@
 
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 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.ts';
+import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.ts';
+import type { BuildManifest } from '../server/build-manifest.ts';
+import { swallow } from '../server/logger.ts';
+import { normalizeBasePath } from '../shared/base-path.ts';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -35,7 +39,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 +67,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
@@ -62,9 +85,18 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
         }
 
         const adapterConfig: TimberConfig = {
+          root: ctx.root,
+          // Normalized once here, not in each adapter: the platform files
+          // adapters write address deployed-URL space (TIM-1274).
+          base: normalizeBasePath(ctx.base),
           output: ctx.config.output ?? 'server',
           clientJavascriptDisabled: ctx.clientJavascript.disabled,
           manifestInit,
+          staticPagesDir:
+            (ctx.config.output ?? 'server') === 'static'
+              ? join(buildDir, 'static-pages')
+              : undefined,
+          staticContentTypes: ctx.staticContentTypes,
         };
 
         await adapter.buildOutput(adapterConfig, buildDir);
@@ -73,6 +105,116 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
   };
 }
 
+/**
+ * Parse the RSC assets manifest at `manifestPath`. Tries JSON.parse first
+ * (fast path for plain-string manifests); falls back to a dynamic import()
+ * for manifests that contain runtime expressions from renderBuiltUrl.
+ * Returns null if both paths fail.
+ */
+async function parseRscManifest(
+  manifestPath: string,
+  content: string
+): Promise<Record<string, unknown> | null> {
+  const jsonStr = content.replace(/^export default\s*/, '').replace(/;?\s*$/, '');
+  try {
+    return JSON.parse(jsonStr);
+  } catch {
+    // Not strict JSON — manifest likely contains renderBuiltUrl runtime
+    // expressions. Fall back to evaluating the module directly.
+  }
+
+  // When renderBuiltUrl's runtime expressions reference external helpers
+  // not defined in the manifest file, this import will fail. That's an
+  // inherent limitation: runtime-computed URLs can't be resolved at build
+  // time for <link> tag injection. The warning below provides observability.
+  try {
+    const url = pathToFileURL(manifestPath).href;
+    const mod = await import(`${url}?t=${Date.now()}`);
+    return mod.default ?? null;
+  } catch (err) {
+    swallow(err, `failed to evaluate RSC assets manifest: ${manifestPath}`, { level: 'warn' });
+    return null;
+  }
+}
+
+/**
+ * Replace all `"js": [...]` array contents with `"js": []` using balanced
+ * bracket matching. Handles nested brackets from runtime expressions like
+ * `__rbu("path/to/[slug]/file.js")`.
+ */
+function clearJsArrays(src: string): string {
+  const pattern = /"js"\s*:\s*\[/g;
+  let result = '';
+  let lastEnd = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(src)) !== null) {
+    const arrayStart = match.index + match[0].length;
+    let depth = 1;
+    let i = arrayStart;
+    while (i < src.length && depth > 0) {
+      if (src[i] === '[') depth++;
+      else if (src[i] === ']') depth--;
+      i++;
+    }
+    result += src.slice(lastEnd, match.index) + '"js": []';
+    lastEnd = i;
+  }
+  result += src.slice(lastEnd);
+  return result;
+}
+
+/**
+ * Replace `"bootstrapScriptContent": <value>` with an empty string. The
+ * value may be a JS expression (e.g., concatenation with runtime helpers),
+ * not a simple string literal. Scans forward from the colon, tracking
+ * balanced parens and brackets, and stops at the next unbalanced `,` or `}`.
+ */
+function clearBootstrapScriptContent(src: string): string {
+  const key = '"bootstrapScriptContent"';
+  const idx = src.indexOf(key);
+  if (idx === -1) return src;
+
+  // Find the colon after the key
+  const colonIdx = src.indexOf(':', idx + key.length);
+  if (colonIdx === -1) return src;
+
+  // Skip whitespace after colon
+  let valStart = colonIdx + 1;
+  while (valStart < src.length && /\s/.test(src[valStart])) valStart++;
+
+  // Scan forward to find the end of the value expression
+  let i = valStart;
+  let depth = 0;
+  let inString = false;
+  let stringChar = '';
+
+  while (i < src.length) {
+    const ch = src[i];
+    if (inString) {
+      if (ch === '\\') {
+        i += 2;
+        continue;
+      }
+      if (ch === stringChar) inString = false;
+    } else {
+      if (ch === '"' || ch === "'") {
+        inString = true;
+        stringChar = ch;
+      } else if (ch === '(' || ch === '[') {
+        depth++;
+      } else if (ch === ')' || ch === ']') {
+        depth--;
+      } else if (depth === 0 && (ch === ',' || ch === '}' || ch === '\n')) {
+        break;
+      }
+    }
+    i++;
+  }
+
+  return src.slice(0, idx) + '"bootstrapScriptContent": ""' + src.slice(i);
+}
+
 /**
  * Strip JS references from the RSC plugin's assets manifest files.
  *
@@ -81,7 +223,74 @@ 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.
  */
-async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
+/**
+ * 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 manifest = await parseRscManifest(manifestPath, content);
+  if (!manifest) 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);
+        }
+      }
+    }
+  }
+}
+
+export async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
   const manifestName = '__vite_rsc_assets_manifest.js';
   const paths = [join(buildDir, 'rsc', manifestName), join(buildDir, 'ssr', manifestName)];
 
@@ -93,16 +302,29 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
       continue;
     }
 
+    // Try JSON.parse to check if we can safely re-serialize
     const jsonStr = content.replace(/^export default\s*/, '').replace(/;?\s*$/, '');
-    let manifest: Record<string, unknown>;
+    let isStrictJson = true;
+    let manifest: Record<string, unknown> | null = null;
     try {
       manifest = JSON.parse(jsonStr);
     } catch {
+      isStrictJson = false;
+    }
+
+    if (!isStrictJson) {
+      // Manifest contains renderBuiltUrl runtime expressions — cannot
+      // safely re-serialize with JSON.stringify. Use targeted text
+      // transforms to clear JS arrays and bootstrapScriptContent.
+      let rewritten = content;
+      rewritten = clearJsArrays(rewritten);
+      rewritten = clearBootstrapScriptContent(rewritten);
+      await writeFile(path, rewritten);
       continue;
     }
 
     // Clear JS from clientReferenceDeps — preserves CSS
-    const deps = manifest.clientReferenceDeps as
+    const deps = manifest?.clientReferenceDeps as
       | Record<string, { js: string[]; css: string[] }>
       | undefined;
     if (deps) {
@@ -111,7 +333,7 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
       }
     }
 
-    manifest.bootstrapScriptContent = '';
+    if (manifest) manifest.bootstrapScriptContent = '';
 
     await writeFile(path, `export default ${JSON.stringify(manifest, null, 2)};\n`);
   }

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,8 +416,62 @@ 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);
+        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 —