@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

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.
@@ -83,7 +87,7 @@ export function parseViteManifest(
     modulepreload[inputPath] = collectTransitiveDeps(inputPath, viteManifest, base);
   }
 
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -196,7 +200,7 @@ export function buildManifestFromBundle(
     css['_global'] = allCss;
   }
 
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -227,6 +231,50 @@ 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;
+}
+
 /**
  * Create the timber-build-manifest Vite plugin.
  *
@@ -242,6 +290,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 +325,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 +339,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');
@@ -298,6 +356,11 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
       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/client-chunks.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+
+/**
+ * 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"`
+ *
+ * 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
+): string {
+  const { normalizedId, serverChunk } = meta;
+
+  // Shared chunks (not associated with a single route entry) get one group.
+  if (serverChunk.startsWith('shared:')) return 'client-shared';
+
+  // Derive the layout boundary from the file's location relative to the
+  // app directory. normalizedId is root-relative (e.g. "app/dashboard/shell.tsx"
+  // or "src/app/dashboard/shell.tsx"). We find the "app/" prefix and walk
+  // segments after it to find the first non-group directory.
+  const relPath = normalizedId.replace(/\\/g, '/');
+
+  // Find the app directory boundary in the path. The last segment of appDir
+  // is the app folder name (usually "app").
+  const appDirName = appDir.replace(/\\/g, '/').split('/').pop() || 'app';
+  const appIdx = relPath.indexOf(appDirName + '/');
+  if (appIdx === -1) return 'client-shared';
+
+  const withinApp = relPath.slice(appIdx + appDirName.length + 1);
+  const segments = withinApp.split('/');
+
+  // Find first directory segment that isn't a route group like (group-a)
+  for (const seg of segments) {
+    // Skip the filename itself
+    if (seg.includes('.')) break;
+    // Skip route groups — parenthesized segments like (group-a)
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    // Found a real route segment
+    return `client-${seg}`;
+  }
+
+  // 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';
+}

package/src/plugins/cloudflare-wasm.ts

@@ -0,0 +1,103 @@
+/**
+ * timber-cloudflare-wasm — Handle WASM modules for Cloudflare Workers builds.
+ *
+ * Cloudflare Workers can natively import `.wasm` files as compiled
+ * WebAssembly.Module. But Rolldown can't load `.wasm` files at build time.
+ *
+ * This plugin bridges the gap:
+ * 1. Adds the `workerd` resolve condition so libraries like @takumi-rs/wasm
+ *    resolve to their Cloudflare-native entry (bare `.wasm` import)
+ * 2. Externalizes `.wasm` imports so Rolldown skips them
+ * 3. Copies the WASM files to the build output so wrangler can find them
+ *
+ * Only active for Cloudflare adapter production builds.
+ */
+
+import { basename, resolve, dirname } from 'node:path';
+import { copyFile, mkdir } from 'node:fs/promises';
+import type { Plugin, ResolvedConfig } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+
+function isCloudflareAdapter(ctx: PluginContext): boolean {
+  const adapter = ctx.config.adapter as { name?: string } | undefined;
+  return adapter?.name === 'cloudflare';
+}
+
+export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
+  // Track resolved WASM file paths so we can copy them to the output
+  const wasmFiles = new Map<string, string>();
+
+  const plugin: Plugin = {
+    name: 'timber-cloudflare-wasm',
+
+    configResolved(resolved: ResolvedConfig) {
+      if (resolved.command !== 'build') return;
+      if (!isCloudflareAdapter(ctx)) return;
+
+      // Prepend `workerd` to resolve conditions for server environments
+      // so @takumi-rs/wasm/auto resolves to the Cloudflare-native entry
+      // (bare WASM import) instead of the Vite entry (?url + fetch).
+      // Must happen in configResolved because the RSC plugin sets its own
+      // conditions during config — merging via config() would lose them.
+      for (const envName of ['rsc', 'ssr']) {
+        const env = resolved.environments[envName];
+        if (!env) continue;
+        const conditions = env.resolve.conditions;
+        if (!conditions.includes('workerd')) {
+          conditions.unshift('workerd');
+        }
+      }
+    },
+
+    resolveId: {
+      order: 'pre',
+      async handler(source, importer) {
+        if (!source.endsWith('.wasm')) return;
+
+        let absolutePath: string;
+        if (source.startsWith('.') && importer) {
+          absolutePath = resolve(dirname(importer), source);
+        } else {
+          return;
+        }
+
+        const filename = basename(absolutePath);
+        wasmFiles.set(filename, absolutePath);
+
+        return { id: './' + filename, external: true };
+      },
+    },
+
+    async writeBundle(options, bundle) {
+      if (wasmFiles.size === 0) return;
+
+      const outDir = options.dir;
+      if (!outDir) return;
+
+      // Find which output chunks reference WASM files and copy the WASM
+      // to the same directory so the relative imports resolve correctly.
+      const targetDirs = new Set<string>();
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== 'chunk') continue;
+        for (const filename of wasmFiles.keys()) {
+          if (chunk.code.includes(filename)) {
+            targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
+          }
+        }
+      }
+
+      if (targetDirs.size === 0) return;
+
+      const copies: Promise<void>[] = [];
+      for (const dir of targetDirs) {
+        await mkdir(dir, { recursive: true });
+        for (const [filename, absolutePath] of wasmFiles) {
+          copies.push(copyFile(absolutePath, resolve(dir, filename)));
+        }
+      }
+      await Promise.all(copies);
+    },
+  };
+
+  return [plugin];
+}

package/src/plugins/content.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',