@timber-js/app 0.2.0-alpha.100 → 0.2.0-alpha.102

package/src/fonts/transform.ts

@@ -7,28 +7,25 @@
  * call sites to static `FontResult` literals so the runtime never has to
  * evaluate the font function.
  *
+ * Uses a single OXC (via vite.parseAst) parse of the source file (via `findFontCallSites`)
+ * and magic-string for precise source rewrites with source maps.
+ *
  * Design doc: 24-fonts.md
  */
 
+import MagicString from 'magic-string';
 import type { ExtractedFont, GoogleFontConfig } from './types.js';
 import { buildFontStack } from './fallbacks.js';
 import { processLocalFont } from './local.js';
 import {
   extractFontConfigAst,
-  extractLocalFontConfigAst,
   detectDynamicFontCallAst,
+  findFontCallSites,
+  extractGoogleFontConfigFromNode,
+  extractLocalFontConfigFromNode,
 } from './ast.js';
 import type { FontPipeline } from './pipeline.js';
 
-/**
- * Regex that matches imports from either `@timber/fonts/google` or
- * `next/font/google` (which the shims plugin resolves to the same virtual
- * module). The transform hook still needs to recognise both spellings in
- * source code.
- */
-const GOOGLE_FONT_IMPORT_RE =
-  /import\s*\{([^}]+)\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"]/g;
-
 /**
  * Convert a font family name to a scoped class name.
  * e.g. "JetBrains Mono" → "timber-font-jetbrains-mono"
@@ -83,29 +80,20 @@ export function detectDynamicFontCall(source: string, importedNames: string[]):
   return detectDynamicFontCallAst(source, importedNames);
 }
 
+// ── Regex-free import/family parsing (thin wrappers over AST) ────────────────
+//
+// These keep the public surface stable. They use `findFontCallSites`
+// internally so they agree with the transform on what counts as an import.
+
 /**
  * Parse the local names imported from `@timber/fonts/google` /
  * `next/font/google`. e.g. `import { Inter, JetBrains_Mono as Mono }` →
  * `['Inter', 'Mono']`.
  */
 export function parseGoogleFontImports(source: string): string[] {
-  const importPattern = new RegExp(GOOGLE_FONT_IMPORT_RE.source, 'g');
-  const names: string[] = [];
-
-  let match;
-  while ((match = importPattern.exec(source)) !== null) {
-    const specifiers = match[1]
-      .split(',')
-      .map((s) => s.trim())
-      .filter(Boolean);
-    for (const spec of specifiers) {
-      // Handle `Inter as MyInter` — we want the local name
-      const parts = spec.split(/\s+as\s+/);
-      names.push(parts[parts.length - 1].trim());
-    }
-  }
-
-  return names;
+  const analysis = findFontCallSites(source);
+  if (!analysis) return [];
+  return analysis.bindings.filter((b) => b.provider === 'google').map((b) => b.localName);
 }
 
 /**
@@ -116,25 +104,14 @@ export function parseGoogleFontImports(source: string): string[] {
  * to the human-readable family name by replacing `_` with a space.
  */
 export function parseGoogleFontFamilies(source: string): Map<string, string> {
-  const importPattern = new RegExp(GOOGLE_FONT_IMPORT_RE.source, 'g');
+  const analysis = findFontCallSites(source);
   const families = new Map<string, string>();
-
-  let match;
-  while ((match = importPattern.exec(source)) !== null) {
-    const specifiers = match[1]
-      .split(',')
-      .map((s) => s.trim())
-      .filter(Boolean);
-    for (const spec of specifiers) {
-      const parts = spec.split(/\s+as\s+/);
-      const originalName = parts[0].trim();
-      const localName = parts[parts.length - 1].trim();
-      // Convert export name back to family name: JetBrains_Mono → JetBrains Mono
-      const family = originalName.replace(/_/g, ' ');
-      families.set(localName, family);
-    }
+  if (!analysis) return families;
+  for (const b of analysis.bindings) {
+    if (b.provider !== 'google') continue;
+    const family = b.importedName.replace(/_/g, ' ');
+    families.set(b.localName, family);
   }
-
   return families;
 }
 
@@ -146,10 +123,10 @@ export function parseGoogleFontFamilies(source: string): Map<string, string> {
  *   import myLoader from 'next/font/local'
  */
 export function parseLocalFontImportName(source: string): string | null {
-  const match = source.match(
-    /import\s+(\w+)\s+from\s*['"](?:@timber\/fonts\/local|@timber-js\/app\/fonts\/local|next\/font\/local)['"]/
-  );
-  return match ? match[1] : null;
+  const analysis = findFontCallSites(source);
+  if (!analysis) return null;
+  const localBinding = analysis.bindings.find((b) => b.provider === 'local');
+  return localBinding?.localName ?? null;
 }
 
 /** Build the static `FontResult` literal we substitute for a font call. */
@@ -162,168 +139,13 @@ function buildFontResultLiteral(extracted: ExtractedFont): string {
 /** Type for the Vite plugin's `this.error` callback. */
 type EmitError = (msg: string) => never;
 
-/**
- * Find Google font calls in `originalCode`, register them in the pipeline,
- * and replace each call site in `transformedCode` with a static FontResult.
- */
-function transformGoogleFonts(
-  transformedCode: string,
-  originalCode: string,
-  importerId: string,
-  pipeline: FontPipeline,
-  emitError: EmitError
-): string {
-  const families = parseGoogleFontFamilies(originalCode);
-  if (families.size === 0) return transformedCode;
-
-  const importedNames = [...families.keys()];
-
-  const dynamicCall = detectDynamicFontCall(originalCode, importedNames);
-  if (dynamicCall) {
-    emitError(
-      `Font function calls must be statically analyzable. ` +
-        `Found dynamic call: ${dynamicCall}. ` +
-        `Pass a literal object with string/array values instead.`
-    );
-  }
-
-  for (const [localName, family] of families) {
-    const callPattern = new RegExp(
-      `(?:const|let|var)\\s+(\\w+)\\s*=\\s*${localName}\\s*\\(\\s*(\\{[\\s\\S]*?\\})\\s*\\)`,
-      'g'
-    );
-
-    let callMatch;
-    while ((callMatch = callPattern.exec(originalCode)) !== null) {
-      const varName = callMatch[1];
-      const configSource = callMatch[2];
-      const fullMatch = callMatch[0];
-
-      const config = extractFontConfig(`(${configSource})`);
-      if (!config) {
-        emitError(
-          `Could not statically analyze font config for ${family}. ` +
-            `Ensure all config values are string literals or arrays of string literals.`
-        );
-      }
-
-      const fontId = generateFontId(family, config!);
-      const className = familyToClassName(family);
-      const fontStack = buildFontStack(family);
-      const display = config!.display ?? 'swap';
-
-      const extracted: ExtractedFont = {
-        id: fontId,
-        family,
-        provider: 'google',
-        weights: normalizeWeightArray(config!.weight),
-        styles: normalizeStyleArray(config!.style),
-        subsets: config!.subsets ?? ['latin'],
-        display,
-        variable: config!.variable,
-        className,
-        fontFamily: fontStack,
-        importer: importerId,
-      };
-
-      pipeline.pruneFor(importerId, family);
-      pipeline.register(extracted);
-
-      const replacement = `const ${varName} = ${buildFontResultLiteral(extracted)}`;
-      transformedCode = transformedCode.replace(fullMatch, replacement);
-    }
-  }
-
-  // Strip the import statement; the values it referred to are now inlined.
-  transformedCode = transformedCode.replace(
-    /import\s*\{[^}]+\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"];?\s*\n?/g,
-    ''
-  );
-
-  return transformedCode;
-}
-
-/**
- * Find local font calls in `originalCode`, register them in the pipeline,
- * and replace each call site in `transformedCode` with a static FontResult.
- */
-function transformLocalFonts(
-  transformedCode: string,
-  originalCode: string,
-  importerId: string,
-  pipeline: FontPipeline,
-  emitError: EmitError
-): string {
-  const localName = parseLocalFontImportName(originalCode);
-  if (!localName) return transformedCode;
-
-  const dynamicCall = detectDynamicFontCall(originalCode, [localName]);
-  if (dynamicCall) {
-    emitError(
-      `Font function calls must be statically analyzable. ` +
-        `Found dynamic call: ${dynamicCall}. ` +
-        `Pass a literal object with string/array values instead.`
-    );
-  }
-
-  const callPattern = new RegExp(
-    `(?:const|let|var)\\s+(\\w+)\\s*=\\s*${localName}\\s*\\(\\s*(\\{[\\s\\S]*?\\})\\s*\\)`,
-    'g'
-  );
-
-  let callMatch;
-  while ((callMatch = callPattern.exec(originalCode)) !== null) {
-    const varName = callMatch[1];
-    const configSource = callMatch[2];
-    const fullMatch = callMatch[0];
-
-    const config = extractLocalFontConfigAst(`(${configSource})`);
-    if (!config) {
-      emitError(
-        `Could not statically analyze local font config. ` +
-          `Ensure src is a string or array of { path, weight?, style? } objects.`
-      );
-    }
-
-    const extracted = processLocalFont(config!, importerId);
-    pipeline.pruneFor(importerId, extracted.family);
-    pipeline.register(extracted);
-
-    const replacement = `const ${varName} = ${buildFontResultLiteral(extracted)}`;
-    transformedCode = transformedCode.replace(fullMatch, replacement);
-  }
-
-  // Strip the import statement; the values it referred to are now inlined.
-  transformedCode = transformedCode.replace(
-    /import\s+\w+\s+from\s*['"](?:@timber\/fonts\/local|@timber-js\/app\/fonts\/local|next\/font\/local)['"];?\s*\n?/g,
-    ''
-  );
-
-  return transformedCode;
-}
-
-/**
- * Run the timber-fonts transform pass on a single source file.
- *
- * Returns the rewritten code (with font calls inlined and a side-effect
- * `import 'virtual:timber-font-css/<hash>.css'` prepended so Vite's CSS
- * pipeline owns the font CSS) or `null` if the file does not import from
- * any timber-fonts virtual module and therefore needs no transformation.
- */
 /**
  * File extensions that may contain real font imports. Only JS/TS module
  * variants are scanned. Excluding non-JS extensions (.mdx, .md, .css,
  * .json, etc.) prevents false-positive matches on text that mentions a
  * font specifier inside documentation, code fences, or asset metadata.
  *
- * Why this matters: the heuristic below is a substring check (`code.includes`),
- * not an AST parse. An MDX file documenting Next.js font compatibility
- * (e.g. a code fence containing `import { Inter } from 'next/font/google'`)
- * would trigger the same match as a real import. The transform then prepends
- * `import 'virtual:timber-font-css/<hash>.css';` to the file, which breaks
- * downstream parsers that require the file to start with their own delimiter
- * — most notably MDX frontmatter, which must start at line 1 col 1 for
- * `remark-frontmatter` to recognise it. See TIM-840.
+ * See TIM-840.
  */
 const FONT_IMPORT_SCANNABLE_EXTENSIONS = new Set([
   '.js',
@@ -337,31 +159,35 @@ const FONT_IMPORT_SCANNABLE_EXTENSIONS = new Set([
 ]);
 
 function hasScannableExtension(id: string): boolean {
-  // Strip Vite query suffixes (?v=..., ?import, ?worker, etc.) before
-  // matching so files imported with a query string are still scanned.
   const path = id.split('?', 1)[0];
   const dot = path.lastIndexOf('.');
   if (dot === -1) return false;
   return FONT_IMPORT_SCANNABLE_EXTENSIONS.has(path.slice(dot).toLowerCase());
 }
 
+/**
+ * Run the timber-fonts transform pass on a single source file.
+ *
+ * Parses the source once with OXC (via vite.parseAst), walks the AST to find font imports
+ * and call sites, then uses magic-string to rewrite call sites to static
+ * `FontResult` literals and strip the import declarations. Returns a
+ * source map alongside the transformed code.
+ *
+ * Returns `null` if the file does not import from any font virtual module.
+ */
 export function runFontsTransform(
   code: string,
   id: string,
   pipeline: FontPipeline,
   emitError: EmitError
-): { code: string; map: null } | null {
+): { code: string; map: ReturnType<MagicString['generateMap']> } | null {
   // Skip virtual modules and node_modules
   if (id.startsWith('\0') || id.includes('node_modules')) return null;
 
-  // Only scan JS/TS module variants. .mdx, .md, .css, .json, etc. may
-  // mention font specifiers in documentation or asset metadata without
-  // ever importing them — a substring match would be a false positive
-  // and the prepended virtual CSS import would corrupt downstream
-  // parsers (e.g. MDX frontmatter, which must start at line 1).
-  // See TIM-840.
+  // Only scan JS/TS module variants (see TIM-840).
   if (!hasScannableExtension(id)) return null;
 
+  // Fast pre-filter: skip files that don't mention any font module.
   const hasGoogleImport =
     code.includes('@timber/fonts/google') ||
     code.includes('@timber-js/app/fonts/google') ||
@@ -372,35 +198,120 @@ export function runFontsTransform(
     code.includes('next/font/local');
   if (!hasGoogleImport && !hasLocalImport) return null;
 
-  let transformedCode = code;
+  // Single parse + AST walk.
+  const analysis = findFontCallSites(code);
+  if (!analysis) return null;
 
-  if (hasGoogleImport) {
-    transformedCode = transformGoogleFonts(transformedCode, code, id, pipeline, emitError);
+  // Bail on dynamic calls.
+  if (analysis.dynamicCall) {
+    emitError(
+      `Font function calls must be statically analyzable. ` +
+        `Found dynamic call: ${analysis.dynamicCall}. ` +
+        `Pass a literal object with string/array values instead.`
+    );
   }
 
-  if (hasLocalImport) {
-    transformedCode = transformLocalFonts(transformedCode, code, id, pipeline, emitError);
+  // Bail on nested font calls (must be module-level).
+  if (analysis.nestedCalls.length > 0) {
+    const first = analysis.nestedCalls[0];
+    emitError(
+      `Font function \`${first.name}()\` must be called at module scope. ` +
+        `Found nested call at line ${first.line}, column ${first.column}. ` +
+        `Move the call to the top level of the module.`
+    );
   }
 
-  if (transformedCode !== code) {
-    // Inject a side-effect import for this file's per-importer virtual
-    // CSS module. The `.css` suffix is what makes Vite's CSS pipeline
-    // own the module — in dev that gives us HMR + source maps, and in
-    // production @vitejs/plugin-rsc walks the RSC module graph via
-    // `collectCss`, finds this virtual CSS import, and injects a
-    // `<link rel="stylesheet" data-rsc-css-href=...>` through React
-    // Float's preinit mechanism (the same path component CSS rides on).
-    //
-    // The per-importer id guarantees two concurrent requests rendering
-    // different routes never see each other's font CSS: each importer's
-    // virtual module only resolves to the fonts that importer registered
-    // via `FontPipeline.getCssForSegment(importer)`. See TIM-828.
-    if (pipeline.size() > 0) {
-      const virtualCssId = pipeline.cssIdMap.idFor(id);
-      transformedCode = `import '${virtualCssId}';\n` + transformedCode;
+  if (analysis.callSites.length === 0 && analysis.bindings.length === 0) return null;
+
+  const s = new MagicString(code);
+
+  // Process each call site.
+  for (const site of analysis.callSites) {
+    if (site.binding.provider === 'google') {
+      const family = site.binding.importedName.replace(/_/g, ' ');
+
+      const config = extractGoogleFontConfigFromNode(site.configNode);
+      if (!config) {
+        emitError(
+          `Could not statically analyze font config for ${family} ` +
+            `at line ${site.line}, column ${site.column}. ` +
+            `Ensure all config values are string literals or arrays of string literals.`
+        );
+      }
+
+      const fontId = generateFontId(family, config!);
+      const className = familyToClassName(family);
+      const fontStack = buildFontStack(family);
+      const display = config!.display ?? 'swap';
+
+      const extracted: ExtractedFont = {
+        id: fontId,
+        family,
+        provider: 'google',
+        weights: normalizeWeightArray(config!.weight),
+        styles: normalizeStyleArray(config!.style),
+        subsets: config!.subsets ?? ['latin'],
+        display,
+        variable: config!.variable,
+        className,
+        fontFamily: fontStack,
+        importer: id,
+      };
+
+      pipeline.pruneFor(id, family);
+      pipeline.register(extracted);
+
+      s.overwrite(site.replaceStart, site.replaceEnd, buildFontResultLiteral(extracted));
+    } else {
+      // local font
+      const config = extractLocalFontConfigFromNode(site.configNode);
+      if (!config) {
+        emitError(
+          `Could not statically analyze local font config ` +
+            `at line ${site.line}, column ${site.column}. ` +
+            `Ensure src is a string or array of { path, weight?, style? } objects.`
+        );
+      }
+
+      const extracted = processLocalFont(config!, id);
+      pipeline.pruneFor(id, extracted.family);
+      pipeline.register(extracted);
+
+      s.overwrite(site.replaceStart, site.replaceEnd, buildFontResultLiteral(extracted));
+    }
+  }
+
+  // Remove font import declarations. Use a Set to avoid double-removing
+  // when multiple bindings come from the same ImportDeclaration.
+  const removedRanges = new Set<string>();
+  for (const imp of analysis.importNodesToRemove) {
+    const key = `${imp.start}:${imp.end}`;
+    if (removedRanges.has(key)) continue;
+    removedRanges.add(key);
+
+    // Also remove the trailing newline if present.
+    let end = imp.end;
+    if (code[end] === '\n') end++;
+    else if (code[end] === '\r' && code[end + 1] === '\n') end += 2;
+    // Also remove a trailing semicolon before the newline.
+    if (code[imp.end] === ';') {
+      end = imp.end + 1;
+      if (code[end] === '\n') end++;
+      else if (code[end] === '\r' && code[end + 1] === '\n') end += 2;
     }
-    return { code: transformedCode, map: null };
+    s.remove(imp.start, end);
+  }
+
+  if (!s.hasChanged()) return null;
+
+  // Inject a side-effect import for the per-importer virtual CSS module.
+  if (pipeline.size() > 0) {
+    const virtualCssId = pipeline.cssIdMap.idFor(id);
+    s.prepend(`import '${virtualCssId}';\n`);
   }
 
-  return null;
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true }),
+  };
 }

package/src/index.ts

@@ -22,7 +22,6 @@ import { timberRouting } from './plugins/routing';
 import { timberShims } from './plugins/shims';
 import { timberFonts } from './plugins/fonts';
 import { timberStaticBuild } from './plugins/static-build';
-import { timberServerActionExports } from './plugins/server-action-exports';
 import { timberBuildManifest } from './plugins/build-manifest';
 import { timberDevLogs } from './dev-tools/logs';
 import { timberDevBrowserLogs } from './dev-tools/browser-logs';
@@ -417,6 +416,20 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       ctx.root = resolved.root;
       ctx.appDir = resolveAppDir(resolved.root, ctx.config.appDir);
       ctx.dev = resolved.command === 'serve';
+
+      // Register all timber config file candidates as Vite config file
+      // dependencies so Vite's built-in restart-on-change handles them
+      // (including atomic writes that emit unlink+add instead of change).
+      // All candidates are registered — not just the one that exists — so
+      // that creating a config file after server start also triggers a
+      // restart. The watcher.add() call in dev-server.ts ensures all
+      // candidates are in the watch set.
+      // See design/21-dev-server.md §HMR Wiring.
+      const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+      for (const name of configNames) {
+        resolved.configFileDependencies.push(resolve(resolved.root, name));
+      }
+
       // Sync buildDir from Vite's resolved build.outDir. Vite keeps
       // outDir as-is (may be relative), so resolve against root.
       ctx.buildDir = resolve(resolved.root, resolved.build.outDir);
@@ -489,7 +502,6 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     // coordinates with plugin-react via __vite_plugin_react_preamble_installed__.
     react(),
     ...reactCompilerPlugins,
-    timberServerActionExports(),
     vitePluginRsc(createRscOptions(ctx, encryptionKeyExpr)),
     timberShims(ctx),
     timberRouting(ctx),

package/src/plugins/dev-server.ts

@@ -84,16 +84,15 @@ export function timberDevServer(ctx: PluginContext): Plugin {
      * filtered out explicitly and passed through to Vite.
      */
     configureServer(server: ViteDevServer) {
-      // Watch config files for full restart.
-      // timber.config.ts is loaded once at startup — any change requires
-      // a full dev server restart. See 21-dev-server.md §HMR Wiring.
+      // Ensure config files are in the watch set. Vite's watcher covers
+      // the project root, but `server.watcher.add()` is a no-op for files
+      // already watched, and ensures newly-created config files (e.g. from
+      // create-timber-app) are picked up. The actual restart logic is
+      // handled by Vite's built-in configFileDependencies check — see the
+      // configResolved hook in index.ts where we register the config path.
+      // See 21-dev-server.md §HMR Wiring.
       const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
-
-      server.watcher.on('change', (filePath: string) => {
-        if (configPaths.includes(filePath)) {
-          server.restart();
-        }
-      });
+      server.watcher.add(configPaths);
 
       // Register Vite server for browser console warning forwarding.
       // See 21-dev-server.md §Dev-Mode Warnings.

package/src/plugins/routing.ts

@@ -15,10 +15,7 @@ import { join } from 'node:path';
 import { scanRoutes } from '../routing/scanner.js';
 import { generateRouteMap } from '../routing/codegen.js';
 import { collectInterceptionRewrites } from '../routing/interception.js';
-import {
-  lintStatusFileDirectives,
-  formatStatusFileLintWarnings,
-} from '../routing/status-file-lint.js';
+
 import {
   lintConventions,
   checkAppDirExists,
@@ -129,14 +126,6 @@ export function timberRouting(ctx: PluginContext): Plugin {
     ctx.timer.end('route-scan');
     writeCodegen(ctx);
 
-    // Lint status files for missing 'use client' directive
-    const statusWarnings = lintStatusFileDirectives(ctx.routeTree);
-    const newStatusWarnings = statusWarnings.filter((w) => !warnedFiles.has(w.filePath));
-    if (newStatusWarnings.length > 0) {
-      for (const w of newStatusWarnings) warnedFiles.add(w.filePath);
-      console.warn(formatStatusFileLintWarnings(newStatusWarnings));
-    }
-
     // Lint conventions (empty app, missing methods, missing root layout)
     const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
     const newConventionWarnings = conventionWarnings.filter((w) => !warnedFiles.has(w.id));