@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

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).

package/src/plugins/cache.ts

@@ -0,0 +1,180 @@
+/**
+ * timber-cache-transform — Vite plugin that injects stable callsite IDs
+ * into `cache()` calls imported from `@timber-js/app/cache`.
+ *
+ * Without this plugin, cache keys use a process-local counter (fnIdCounter)
+ * which is unstable across cold starts in serverless/multi-instance
+ * deployments. With a shared CacheHandler (Redis/KV), colliding counters
+ * cause cache key poisoning — serving one route's cached data to another.
+ *
+ * The plugin transforms:
+ *   cache(fn, opts)  →  cache(fn, opts, "stable-id")
+ *
+ * where stable-id = fnv1a(relativeModulePath + ":cache:" + callIndex).
+ *
+ * See TIM-997, design/06-caching.md §"Cache Key Security".
+ */
+
+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 { fnv1aHash } from '../cache/fast-hash.js';
+
+const CACHE_MODULE_SOURCES = new Set(['@timber-js/app/cache', 'timber/cache']);
+
+interface PositionedNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+
+interface IdentifierNode extends PositionedNode {
+  type: 'Identifier';
+  name: string;
+}
+
+interface ImportDeclarationNode extends PositionedNode {
+  type: 'ImportDeclaration';
+  source: { value: string };
+  specifiers: Array<
+    PositionedNode & {
+      type: string;
+      local: IdentifierNode;
+      imported?: IdentifierNode;
+    }
+  >;
+}
+
+interface CallExpressionNode extends PositionedNode {
+  type: 'CallExpression';
+  callee: PositionedNode;
+  arguments: PositionedNode[];
+}
+
+interface ProgramNode extends PositionedNode {
+  type: 'Program';
+  body: PositionedNode[];
+}
+
+/**
+ * Find the local binding name(s) for `cache` imported from the cache module.
+ */
+function findCacheBindings(program: ProgramNode): Set<string> {
+  const bindings = new Set<string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ImportDeclaration') continue;
+    const decl = stmt as unknown as ImportDeclarationNode;
+    if (!CACHE_MODULE_SOURCES.has(decl.source.value)) continue;
+    for (const spec of decl.specifiers) {
+      if (spec.type !== 'ImportSpecifier') continue;
+      const importedName = spec.imported?.name ?? spec.local.name;
+      if (importedName === 'cache') {
+        bindings.add(spec.local.name);
+      }
+    }
+  }
+  return bindings;
+}
+
+/**
+ * Recursively walk AST nodes to find cache() call expressions.
+ *
+ * cache() is typically called at module scope, but we also handle calls
+ * inside functions/blocks for completeness.
+ */
+function findCacheCallSites(
+  node: PositionedNode,
+  cacheBindings: Set<string>,
+  results: CallExpressionNode[]
+): void {
+  if (node.type === 'CallExpression') {
+    const call = node as unknown as CallExpressionNode;
+    if (
+      call.callee.type === 'Identifier' &&
+      cacheBindings.has((call.callee as IdentifierNode).name) &&
+      call.arguments.length === 2
+    ) {
+      results.push(call);
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end') continue;
+    const val = node[key];
+    if (val && typeof val === 'object') {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item && typeof item === 'object' && typeof item.type === 'string') {
+            findCacheCallSites(item as PositionedNode, cacheBindings, results);
+          }
+        }
+      } else if (typeof (val as PositionedNode).type === 'string') {
+        findCacheCallSites(val as PositionedNode, cacheBindings, results);
+      }
+    }
+  }
+}
+
+/**
+ * Generate a stable callsite ID from a module path and call index.
+ *
+ * The ID is an FNV-1a hash of the relative module path + call index,
+ * providing a deterministic identifier that is:
+ * - Stable across cold starts of the same build
+ * - Unique across different modules
+ * - Unique across multiple cache() calls within the same module
+ */
+function generateStableId(relativeModulePath: string, callIndex: number): string {
+  return fnv1aHash(`${relativeModulePath}:cache:${callIndex}`);
+}
+
+export function timberCacheTransform(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-cache-transform',
+
+    transform(code, 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;
+
+      let program: ProgramNode;
+      try {
+        program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+      } catch {
+        return;
+      }
+
+      const cacheBindings = findCacheBindings(program);
+      if (cacheBindings.size === 0) return;
+
+      const callSites: CallExpressionNode[] = [];
+      findCacheCallSites(program, cacheBindings, callSites);
+      if (callSites.length === 0) return;
+
+      // Sort by position in file for deterministic call indices
+      callSites.sort((a, b) => a.start - b.start);
+
+      const root = ctx.root || process.cwd();
+      const relPath = relative(root, id);
+      const s = new MagicString(code);
+
+      for (let i = 0; i < callSites.length; i++) {
+        const call = callSites[i];
+        const stableId = generateStableId(relPath, i);
+        // Insert the stable ID as the 3rd argument just before the closing ')'
+        const insertPos = call.end - 1;
+        s.appendLeft(insertPos, `, "${stableId}"`);
+      }
+
+      return {
+        code: s.toString(),
+        map: s.generateMap({ hires: 'boundary' }),
+      };
+    },
+  };
+}
+
+// Exported for testing
+export { generateStableId };

package/src/plugins/client-chunks.ts

@@ -0,0 +1,113 @@
+/**
+ * Client chunk grouping strategy for @vitejs/plugin-rsc.
+ *
+ * Groups client reference modules by layout boundary to balance route-scoped
+ * code splitting with HTTP request count. A constant group name would collapse
+ * all routes into one chunk (every page downloads every client component).
+ * Per-serverChunk grouping creates many sub-500B files. Layout-boundary
+ * grouping is the middle ground.
+ *
+ * See design/27-chunking-strategy.md, TIM-440, TIM-499.
+ */
+
+import { relative } from 'node:path';
+
+/**
+ * Check whether a root-relative path lives under the app directory,
+ * and if so return the first non-group route segment.
+ *
+ * `appPrefix` is the root-relative app directory with a trailing slash
+ * (e.g. "app/" or "src/app/"), computed once from the resolved appDir
+ * and root. Matching uses `startsWith` — no ambiguity.
+ *
+ * Returns:
+ *   { inApp: false }                       — path is not under app/
+ *   { inApp: true, segment: null }         — root of app/ (e.g. app/layout.tsx)
+ *   { inApp: true, segment: "dashboard" }  — nested route boundary
+ */
+function findAppBoundary(
+  path: string,
+  appPrefix: string
+): { inApp: false } | { inApp: true; segment: string | null } {
+  const relPath = path.replace(/\\/g, '/');
+  if (!relPath.startsWith(appPrefix)) return { inApp: false };
+
+  const withinApp = relPath.slice(appPrefix.length);
+  const segments = withinApp.split('/');
+
+  for (const seg of segments) {
+    if (seg.includes('.')) break;
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    return { inApp: true, segment: seg };
+  }
+
+  return { inApp: true, segment: null };
+}
+
+/**
+ * Derive a chunk group name for a client reference module.
+ *
+ * Groups by the first non-group route segment under appDir so that all
+ * client components belonging to the same layout boundary land in one
+ * chunk. For example:
+ *   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
+ *   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
+ *   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
+ *   - `shared:...` (shared across chunks) → `"client-shared"`
+ *
+ * When a 'use client' module lives outside the app directory (e.g. in
+ * src/posts/ or src/components/), the function falls back to deriving
+ * the layout boundary from the serverChunk's facade path. This prevents
+ * lazily-loaded client dependencies (e.g. via import.meta.glob) from
+ * being hoisted into the shared chunk when they're only used by a
+ * specific route.
+ *
+ * This balances route-scoped code splitting with HTTP request count:
+ * fewer chunks than per-serverChunk, but still avoids downloading every
+ * client component on every page.
+ */
+export function clientChunkGroup(
+  meta: { id: string; normalizedId: string; serverChunk: string },
+  appDir: string,
+  root: string
+): string {
+  const { normalizedId, serverChunk } = meta;
+
+  // Shared chunks (not associated with a single route entry) get one group.
+  if (serverChunk.startsWith('shared:')) return 'client-shared';
+
+  // Compute the root-relative app directory prefix once. Both normalizedId
+  // and serverChunk paths from the RSC plugin are root-relative (via
+  // path.relative(root, absoluteId)), so this prefix matches exactly —
+  // no ambiguity with content directories that happen to share a name.
+  const appPrefix = relative(root, appDir).replace(/\\/g, '/') + '/';
+
+  // Try the client module's own path first.
+  const result = findAppBoundary(normalizedId, appPrefix);
+  if (result.inApp && result.segment) return `client-${result.segment}`;
+  if (result.inApp) return 'client-shared';
+
+  // The client module lives outside the app directory (e.g. src/posts/,
+  // src/components/). Fall back to the serverChunk's facade path — the
+  // RSC entry point that imported this module — to derive the route's
+  // layout boundary. This keeps dependencies of lazily-loaded 'use client'
+  // components (e.g. from import.meta.glob) in per-route async chunks
+  // instead of hoisting them into client-shared.
+  if (serverChunk.startsWith('facade:')) {
+    const facadePath = serverChunk.slice('facade:'.length).replace(/\\/g, '/');
+    const facadeResult = findAppBoundary(facadePath, appPrefix);
+    if (facadeResult.inApp && facadeResult.segment) return `client-${facadeResult.segment}`;
+    if (facadeResult.inApp) return 'client-shared';
+
+    // Both module and facade are outside app/. Derive a chunk name from
+    // the full facade path to keep these isolated from client-shared.
+    // Uses the full path (minus extension) to avoid collisions between
+    // facades with the same basename (e.g. foo/index.mdx vs bar/index.mdx).
+    const facadeName = facadePath.replace(/\.[^.]+$/, '').replace(/\//g, '-');
+    if (facadeName) return `client-${facadeName}`;
+  }
+
+  // Root-level files (layout.tsx, page.tsx directly in app/) go into the
+  // shared group since the root layout is loaded on every page.
+  return 'client-shared';
+}