@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.41

package/src/plugins/fonts.ts

@@ -14,13 +14,15 @@
  * Design doc: 24-fonts.md
  */
 
-import type { Plugin } from 'vite';
+import type { Plugin, ViteDevServer } from 'vite';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
 import type { PluginContext } from '#/index.js';
 import type { ExtractedFont, GoogleFontConfig } from '#/fonts/types.js';
 import type { ManifestFontEntry } from '#/server/build-manifest.js';
-import { generateVariableClass, generateFontFamilyClass } from '#/fonts/css.js';
+import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from '#/fonts/css.js';
 import { generateFallbackCss, buildFontStack } from '#/fonts/fallbacks.js';
-import { processLocalFont } from '#/fonts/local.js';
+import { processLocalFont, generateLocalFontFaces } from '#/fonts/local.js';
 import { inferFontFormat } from '#/fonts/local.js';
 import { downloadAndCacheFonts, type CachedFont } from '#/fonts/google.js';
 import {
@@ -34,6 +36,23 @@ const VIRTUAL_LOCAL = '@timber/fonts/local';
 const RESOLVED_GOOGLE = '\0@timber/fonts/google';
 const RESOLVED_LOCAL = '\0@timber/fonts/local';
 
+/**
+ * Virtual side-effect module that registers font CSS on globalThis.
+ *
+ * When a file calls localFont() or a Google font function, the transform
+ * hook injects `import 'virtual:timber-font-css-register'` into that file.
+ * This virtual module sets `globalThis.__timber_font_css` with the combined
+ * @font-face CSS. The RSC entry reads it at render time to inline a <style> tag.
+ *
+ * This approach avoids timing issues because:
+ * 1. The font file is in the RSC module graph (imported by layout.tsx)
+ * 2. The side-effect import is added to the font file during transform
+ * 3. When layout.tsx is loaded, fonts.ts runs → side-effect module runs → globalThis is set
+ * 4. RSC entry renders → reads globalThis → inlines <style>
+ */
+const VIRTUAL_FONT_CSS_REGISTER = 'virtual:timber-font-css-register';
+const RESOLVED_FONT_CSS_REGISTER = '\0virtual:timber-font-css-register';
+
 /**
  * Registry of fonts extracted during transform.
  * Keyed by a unique font ID derived from family + config.
@@ -242,27 +261,44 @@ function generateLocalVirtualModule(): string {
   ].join('\n');
 }
 
+/**
+ * Generate CSS for a single extracted font.
+ *
+ * Includes @font-face rules (for local fonts), fallback @font-face,
+ * and the scoped class rule.
+ */
+export function generateFontCss(font: ExtractedFont): string {
+  const cssParts: string[] = [];
+
+  if (font.provider === 'local' && font.localSources) {
+    const faces = generateLocalFontFaces(font.family, font.localSources, font.display);
+    const faceCss = generateFontFaces(faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  const fallbackCss = generateFallbackCss(font.family);
+  if (fallbackCss) cssParts.push(fallbackCss);
+
+  if (font.variable) {
+    cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
+  } else {
+    cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
+  }
+
+  return cssParts.join('\n\n');
+}
+
 /**
  * Generate the CSS output for all extracted fonts.
  *
- * Includes @font-face rules, fallback @font-face rules, and scoped classes.
+ * Includes @font-face rules for local fonts, fallback @font-face rules,
+ * and scoped classes.
  */
 export function generateAllFontCss(registry: FontRegistry): string {
   const cssParts: string[] = [];
-
   for (const font of registry.values()) {
-    // Generate fallback @font-face if metrics are available
-    const fallbackCss = generateFallbackCss(font.family);
-    if (fallbackCss) cssParts.push(fallbackCss);
-
-    // Generate scoped class
-    if (font.variable) {
-      cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
-    } else {
-      cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
-    }
+    cssParts.push(generateFontCss(font));
   }
-
   return cssParts.join('\n\n');
 }
 
@@ -359,23 +395,112 @@ export function timberFonts(ctx: PluginContext): Plugin {
     name: 'timber-fonts',
 
     /**
-     * Resolve `@timber/fonts/google` and `@timber/fonts/local` to virtual modules.
+     * Resolve `@timber/fonts/google`, `@timber/fonts/local`,
+     * and `virtual:timber-font-css` virtual modules.
+     *
+     * Handles \0 prefix and root prefix stripping for RSC/SSR
+     * environments where the RSC plugin re-imports virtual modules
+     * with additional prefixes.
      */
     resolveId(id: string) {
-      if (id === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
-      if (id === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+      // Strip \0 prefix (RSC plugin re-imports)
+      let cleanId = id.startsWith('\0') ? id.slice(1) : id;
+      // Strip root prefix (SSR build entries)
+      if (cleanId.startsWith(ctx.root)) {
+        const stripped = cleanId.slice(ctx.root.length);
+        if (stripped.startsWith('/') || stripped.startsWith('\\')) {
+          cleanId = stripped.slice(1);
+        } else {
+          cleanId = stripped;
+        }
+      }
+
+      if (cleanId === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
+      if (cleanId === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+      if (cleanId === VIRTUAL_FONT_CSS_REGISTER) return RESOLVED_FONT_CSS_REGISTER;
       return null;
     },
 
     /**
      * Return generated source for font virtual modules.
+     *
+     * `virtual:timber-font-css` exports the combined @font-face CSS
+     * as a string. The RSC entry imports it and inlines a <style> tag.
+     * Because this is loaded lazily (on first request), the font
+     * registry is always populated by the time it's needed.
      */
     load(id: string) {
       if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(registry);
       if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
+
+      if (id === RESOLVED_FONT_CSS_REGISTER) {
+        const css = generateAllFontCss(registry);
+        // Side-effect module: sets font CSS on globalThis for the RSC entry to read.
+        return `globalThis.__timber_font_css = ${JSON.stringify(css)};`;
+      }
       return null;
     },
 
+    /**
+     * Serve local font files and font CSS in dev mode under `/_timber/fonts/`.
+     *
+     * Serves:
+     * - `/_timber/fonts/fonts.css` — combined @font-face + scoped class CSS
+     * - `/_timber/fonts/<filename>` — individual font files from the registry
+     *
+     * Only files registered in the font registry are served.
+     * Paths are validated to prevent directory traversal.
+     */
+    configureServer(server: ViteDevServer) {
+      server.middlewares.use((req, res, next) => {
+        const url = req.url;
+        if (!url || !url.startsWith('/_timber/fonts/')) return next();
+
+        const requestedFilename = url.slice('/_timber/fonts/'.length);
+        // Reject path traversal attempts
+        if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
+          res.statusCode = 400;
+          res.end('Bad request');
+          return;
+        }
+
+        // Font CSS is now injected via Vite's CSS pipeline (virtual:timber-font-css modules).
+        // This middleware only serves font binary files (woff2, etc.).
+
+        // Find the matching font file in the registry
+        for (const font of registry.values()) {
+          if (font.provider !== 'local' || !font.localSources) continue;
+          for (const src of font.localSources) {
+            const basename = src.path.split('/').pop() ?? '';
+            if (basename === requestedFilename) {
+              const absolutePath = normalize(resolve(src.path));
+              if (!existsSync(absolutePath)) {
+                res.statusCode = 404;
+                res.end('Not found');
+                return;
+              }
+              const data = readFileSync(absolutePath);
+              const ext = absolutePath.split('.').pop()?.toLowerCase();
+              const mimeMap: Record<string, string> = {
+                woff2: 'font/woff2',
+                woff: 'font/woff',
+                ttf: 'font/ttf',
+                otf: 'font/otf',
+                eot: 'application/vnd.ms-fontopen',
+              };
+              res.setHeader('Content-Type', mimeMap[ext ?? ''] ?? 'application/octet-stream');
+              res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+              res.setHeader('Access-Control-Allow-Origin', '*');
+              res.end(data);
+              return;
+            }
+          }
+        }
+
+        next();
+      });
+    },
+
     /**
      * Download and cache Google Fonts during production builds.
      *
@@ -499,6 +624,11 @@ export function timberFonts(ctx: PluginContext): Plugin {
       }
 
       if (transformedCode !== code) {
+        // Inject side-effect import that registers font CSS on globalThis.
+        // The RSC entry reads globalThis.__timber_font_css to inline a <style> tag.
+        if (registry.size > 0) {
+          transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
+        }
         return { code: transformedCode, map: null };
       }
 
@@ -525,6 +655,28 @@ export function timberFonts(ctx: PluginContext): Plugin {
         });
       }
 
+      // Emit local font files as assets
+      for (const font of registry.values()) {
+        if (font.provider !== 'local' || !font.localSources) continue;
+        for (const src of font.localSources) {
+          const absolutePath = normalize(resolve(src.path));
+          if (!existsSync(absolutePath)) {
+            this.warn(`Local font file not found: ${absolutePath}`);
+            continue;
+          }
+          const basename = src.path.split('/').pop() ?? src.path;
+          const data = readFileSync(absolutePath);
+          this.emitFile({
+            type: 'asset',
+            fileName: `_timber/fonts/${basename}`,
+            source: data,
+          });
+        }
+      }
+
+      // Font CSS is emitted by Vite's CSS pipeline via virtual:timber-font-css modules.
+      // We only need to emit font binary files and update the build manifest here.
+
       if (!ctx.buildManifest) return;
 
       // Build a lookup from font family → cached files for manifest entries

package/src/plugins/mdx.ts

@@ -16,19 +16,23 @@ import type { PluginContext } from '#/index.js';
 const MDX_EXTENSIONS = ['mdx', 'md'];
 
 /**
- * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root.
+ * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
+ * or in src/. Root takes precedence, matching Next.js behavior.
  * Returns the absolute path if found, otherwise undefined.
  */
-function findMdxComponents(root: string): string | undefined {
+export function findMdxComponents(root: string): string | undefined {
   const candidates = [
     'mdx-components.tsx',
     'mdx-components.ts',
     'mdx-components.jsx',
     'mdx-components.js',
   ];
-  for (const name of candidates) {
-    const p = join(root, name);
-    if (existsSync(p)) return p;
+  const dirs = [root, join(root, 'src')];
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const p = join(dir, name);
+      if (existsSync(p)) return p;
+    }
   }
   return undefined;
 }

package/src/plugins/routing.ts

@@ -28,7 +28,7 @@ const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|default|denied|search-params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|default|denied|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
@@ -168,20 +168,49 @@ export function timberRouting(ctx: PluginContext): Plugin {
       // Watch the app directory
       devServer.watcher.add(ctx.appDir);
 
-      const handleFileChange = (filePath: string) => {
-        // Only react to route-significant files in the app directory
+      /** Snapshot of the last generated manifest, used to detect structural changes. */
+      let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : '';
+
+      /**
+       * Handle a route-significant file being added or removed.
+       * Always triggers a full-reload since the route tree structure changed.
+       */
+      const handleStructuralChange = (filePath: string) => {
         if (!filePath.startsWith(ctx.appDir)) return;
         if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 
-        // Rescan the route tree
         rescan();
-
-        // Invalidate the virtual module in all environments
+        lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : '';
         invalidateManifest(devServer);
       };
 
-      devServer.watcher.on('add', handleFileChange);
-      devServer.watcher.on('unlink', handleFileChange);
+      /**
+       * Handle a route file's content changing.
+       *
+       * Most content edits (JSX changes, fixing typos) don't affect route
+       * metadata — Vite's React Fast Refresh handles those via normal HMR.
+       * Only rescan and full-reload when route metadata actually changed
+       * (e.g., searchParams export added/removed, metadata export changed).
+       */
+      const handleContentChange = (filePath: string) => {
+        if (!filePath.startsWith(ctx.appDir)) return;
+        if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
+
+        rescan();
+        const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : '';
+        if (newManifest !== lastManifest) {
+          lastManifest = newManifest;
+          invalidateManifest(devServer);
+        }
+        // Otherwise: content edit didn't change route metadata — let Vite HMR handle it
+      };
+
+      devServer.watcher.on('add', handleStructuralChange);
+      devServer.watcher.on('unlink', handleStructuralChange);
+      // Watch content changes to page files — searchParams detection depends
+      // on file contents (export const searchParams), not just file presence.
+      // But only full-reload when route metadata actually changes.
+      devServer.watcher.on('change', handleContentChange);
       // Also watch renames (which are add+unlink) — handled by the above
     },
   };
@@ -301,12 +330,9 @@ function generateManifestModule(tree: RouteTree): string {
         `${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`
       );
     }
-    if (node.searchParams) {
-      const v = addImport(node.searchParams);
-      parts.push(
-        `${nextIndent}searchParams: { load: ${v}, filePath: ${JSON.stringify(node.searchParams.filePath)} },`
-      );
-    }
+    // searchParams is now a named export from page.tsx, not a separate file.
+    // The page module's searchParams export is loaded via the page's lazy import.
+    // Runtime registration happens in the route loader using the page module.
 
     // Status-code files
     if (node.statusFiles && node.statusFiles.size > 0) {

package/src/plugins/server-bundle.ts

@@ -137,5 +137,36 @@ export function timberServerBundle(): Plugin[] {
     },
   };
 
-  return [bundlePlugin, esmInitFixPlugin];
+  // Fix Rolldown's `createRequire(import.meta.url)` CJS interop shim for
+  // Cloudflare Workers. Rolldown emits this for CJS dependencies (e.g.
+  // @opentelemetry/context-async-hooks) that use `require()`. On Workers,
+  // `import.meta.url` is `undefined` for non-entry modules, causing:
+  //   TypeError: The argument 'path' must be a file URL object, a file URL
+  //   string, or an absolute path string. Received 'undefined'
+  //
+  // The fix: provide a fallback URL when `import.meta.url` is undefined.
+  // The actual URL doesn't matter — `createRequire` only needs it for
+  // resolving relative paths, but the only `__require()` calls are for
+  // Node built-ins (events, async_hooks) which resolve from any base.
+  //
+  // The top-level `ssr: { target: 'webworker' }` was supposed to prevent
+  // this, but it doesn't propagate to custom environments (rsc) in Vite's
+  // Environment API. See LOCAL-405.
+  const createRequireFixPlugin: Plugin = {
+    name: 'timber-create-require-fix',
+    applyToEnvironment(environment) {
+      return environment.name === 'rsc' || environment.name === 'ssr';
+    },
+    renderChunk(code) {
+      const pattern = 'createRequire(import.meta.url)';
+      if (!code.includes(pattern)) return null;
+
+      return {
+        code: code.replace(pattern, 'createRequire(import.meta.url || "file:///app")'),
+        map: null,
+      };
+    },
+  };
+
+  return [bundlePlugin, esmInitFixPlugin, createRequireFixPlugin];
 }

package/src/plugins/shims.ts

@@ -137,7 +137,7 @@ export function timberShims(_ctx: PluginContext): Plugin {
       // package.json exports), creating a module instance split: ssr-entry.ts
       // registers the ALS-backed SSR data provider on the src/ instance of
       // ssr-data.ts, but client component hooks read getSsrData() from the
-      // dist/ instance — which has no provider. Result: hooks like useParams()
+      // dist/ instance — which has no provider. Result: hooks like useSegmentParams()
       // return empty defaults during SSR.
       //
       // This remap is SSR-only. The RSC environment still resolves to dist/

package/src/plugins/static-build.ts

@@ -163,9 +163,6 @@ export function validateStaticMode(
  * - transform: Validates source files for static mode violations
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-  const clientJavascriptDisabled = ctx.clientJavascript.disabled;
-
   return {
     name: 'timber-static-build',
 
@@ -177,6 +174,11 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
      * - When client JS disabled: 'use client' / 'use server' directives → build error
      */
     transform(code: string, id: string) {
+      // Read ctx.config lazily inside the hook — not at plugin construction
+      // time — so file-based config from timber.config.ts is respected.
+      // See TIM-451.
+      const isStatic = ctx.config.output === 'static';
+
       // Only active in static mode
       if (!isStatic) return null;
 
@@ -189,7 +191,9 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
       // Only check JS/TS files
       if (!/\.[jt]sx?$/.test(id)) return null;
 
-      const errors = validateStaticMode(code, id, { clientJavascriptDisabled });
+      const errors = validateStaticMode(code, id, {
+        clientJavascriptDisabled: ctx.clientJavascript.disabled,
+      });
 
       if (errors.length > 0) {
         // Format all errors into a single build error message