@timber-js/app 0.2.0-alpha.158 → 0.2.0-alpha.159

package/src/fonts/transform.ts

@@ -139,32 +139,6 @@ function buildFontResultLiteral(extracted: ExtractedFont): string {
 /** Type for the Vite plugin's `this.error` callback. */
 type EmitError = (msg: string) => never;
 
-/**
- * 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.
- *
- * See TIM-840.
- */
-const FONT_IMPORT_SCANNABLE_EXTENSIONS = new Set([
-  '.js',
-  '.jsx',
-  '.ts',
-  '.tsx',
-  '.mjs',
-  '.cjs',
-  '.mts',
-  '.cts',
-]);
-
-function hasScannableExtension(id: string): boolean {
-  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.
  *
@@ -174,6 +148,10 @@ function hasScannableExtension(id: string): boolean {
  * source map alongside the transformed code.
  *
  * Returns `null` if the file does not import from any font virtual module.
+ *
+ * Pre-filtering (extension allow-list, node_modules exclusion, and code
+ * substring checks) is handled by Vite 8's rolldown-native `transform.filter`
+ * in the plugin hook definition (plugins/fonts.ts). See TIM-840, TIM-1147.
  */
 export function runFontsTransform(
   code: string,
@@ -181,23 +159,6 @@ export function runFontsTransform(
   pipeline: FontPipeline,
   emitError: EmitError
 ): { 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 (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') ||
-    code.includes('next/font/google');
-  const hasLocalImport =
-    code.includes('@timber/fonts/local') ||
-    code.includes('@timber-js/app/fonts/local') ||
-    code.includes('next/font/local');
-  if (!hasGoogleImport && !hasLocalImport) return null;
-
   // Single parse + AST walk.
   const analysis = findFontCallSites(code);
   if (!analysis) return null;

package/src/index.ts

@@ -24,12 +24,14 @@ import { timberFonts } from './plugins/fonts';
 import { timberStaticBuild } from './plugins/static-build';
 import { timberBuildManifest } from './plugins/build-manifest';
 import { timberDevLogs } from './dev-tools/logs';
-import { timberDevBrowserLogs } from './dev-tools/browser-logs';
+import { resolveForwardConsole } from './dev-tools/browser-logs';
 import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
 import { clientChunkGroup } from './plugins/client-chunks';
 import { timberServerBundle } from './plugins/server-bundle';
 import { timberCacheTransform } from './plugins/cache';
+import { timberPrebuilt } from './plugins/prebuilt';
+import { timberPrerenderSugar } from './plugins/prerender-sugar';
 import { timberCloudflareWasm } from './plugins/cloudflare-wasm';
 import { timberAdapterBuild } from './plugins/adapter-build';
 import { timberBuildReport } from './plugins/build-report';
@@ -416,7 +418,11 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // auto-bump from 3000. Explicit preview uses strictPort: true
       // so conflicts fail loudly, matching the dev behavior and the
       // TIM-842 spec.
-      const serverConfig: { port?: number; strictPort?: boolean } = {};
+      const serverConfig: {
+        port?: number;
+        strictPort?: boolean;
+        forwardConsole?: boolean | { unhandledErrors?: boolean; logLevels?: string[] };
+      } = {};
       const previewConfig: { port?: number; strictPort?: boolean } = {};
       if (resolvedDevPort != null) {
         if (!isPreview) {
@@ -426,6 +432,12 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
         previewConfig.port = resolvedDevPort;
         previewConfig.strictPort = resolvedDevPortExplicit;
       }
+
+      // Enable Vite 8's built-in browser→terminal console forwarding.
+      // Vite defaults this OFF for non-agent dev; timber enables it based
+      // on the devBrowserLogs config (default: 'warn'). See TIM-1152.
+      serverConfig.forwardConsole = resolveForwardConsole(ctx.config.devBrowserLogs);
+
       return {
         build: { outDir: buildOutDir },
         environments: envOutDirs,
@@ -535,6 +547,8 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     timberFonts(ctx),
     timberMdx(ctx),
     timberCacheTransform(ctx),
+    timberPrerenderSugar(ctx), // export const prerender → cache.component() desugaring
+    timberPrebuilt(ctx), // cache.component() → __prebuilt() callsite rewrite
     timberContent(ctx),
     timberServerBundle(), // Bundle all deps in server environments for prod
     timberCloudflareWasm(ctx), // Externalize WASM for Cloudflare Workers
@@ -542,7 +556,6 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     timberBuildReport(ctx), // Post-build: route table with bundle sizes
     timberAdapterBuild(ctx), // Post-build: invoke adapter.buildOutput()
     timberDevLogs(ctx), // Dev-only: forward server console.* to browser console
-    timberDevBrowserLogs(ctx), // Dev-only: forward browser console.* to server terminal
     timberDevServer(ctx), // Must be last — configureServer post-hook runs after all watchers
   ];
 }

package/src/plugin-context.ts

@@ -13,6 +13,7 @@ import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import type { RouteTree } from './routing/types';
 import type { BuildManifest } from './server/build-manifest';
+import type { CaptureSummary } from './server/prebuilt-builder';
 import type { StartupTimer } from './utils/startup-timer';
 import { createStartupTimer } from './utils/startup-timer';
 import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
@@ -103,6 +104,41 @@ export interface PluginContext {
    * See design/27-chunking-strategy.md, TIM-1107.
    */
   sharedModuleFacades?: Map<string, string[]>;
+  /**
+   * Module ID → prebuilt component IDs declared in it. Recorded by the
+   * timber-prebuilt transform (RSC environment, production builds only),
+   * consumed by the RSC `generateBundle` module-graph walk that computes
+   * `routePrebuiltComponents`. See design/44-render-at-build-time.md.
+   */
+  prebuiltModuleComponents?: Map<string, string[]>;
+  /**
+   * Module ID → mapping of variable name to component ID for the prebuilt
+   * components declared in that module. Used at `generateBundle` time to
+   * trace imports from other modules back to specific component IDs.
+   */
+  prebuiltBindingNames?: Map<string, Map<string, string>>;
+  /**
+   * Component ID → distinct static call-site prop objects captured from
+   * JSX usage sites during the transform and generateBundle phases.
+   * Consumed by the post-build capture pass to render with actual props
+   * instead of empty `{}`. See design/44 §Props Derivation.
+   */
+  prebuiltCallSiteProps?: Map<string, Record<string, unknown>[]>;
+  /**
+   * Route file path (page or layout, absolute) → prebuilt component IDs
+   * transitively reachable from it. Computed during RSC `generateBundle`,
+   * consumed by the post-build capture pass (TIM-1119) to decide which
+   * components to render under which route's param combos.
+   */
+  routePrebuiltComponents?: Map<string, string[]>;
+  /**
+   * Page file paths that were desugared from `export const prerender` by
+   * timber-prerender-sugar. The prebuilt transform uses this to verify
+   * the generated `cache.component(...)` call was picked up.
+   */
+  prerenderSugarPages?: Set<string>;
+  /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */
+  captureSummary?: CaptureSummary;
 }
 
 // ── App directory resolution ──────────────────────────────────────────────

package/src/plugins/build-report.ts

@@ -13,11 +13,14 @@
  * Task: TIM-287
  */
 
-import { relative } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import type { SegmentNode, RouteTree } from '../routing/types.js';
+import type { CaptureSummary } from '../server/prebuilt-builder.js';
+import type { PrebuiltManifest } from '../server/prebuilt/payload-source.js';
 import { collectLeafRoutes } from '../routing/walkers.js';
 import { formatSize } from '../utils/format.js';
 
@@ -186,6 +189,120 @@ function stripAnsi(str: string): string {
   return str.replace(/\u001b\[\d+m/g, '');
 }
 
+// ─── Prebuilt component stats ────────────────────────────────────────────
+
+export interface PrebuiltComponentStats {
+  componentId: string;
+  entryCount: number;
+  totalBytes: number;
+}
+
+export interface PrebuiltReportData {
+  components: PrebuiltComponentStats[];
+  totalEntries: number;
+  totalBytes: number;
+  skippedCount: number;
+  skippedReasons: Array<{ componentId: string; route: string; message: string }>;
+}
+
+export function loadPrebuiltManifest(buildDir: string): PrebuiltManifest | null {
+  try {
+    const raw = readFileSync(join(buildDir, 'prebuilt', 'manifest.json'), 'utf-8');
+    return JSON.parse(raw) as PrebuiltManifest;
+  } catch {
+    return null;
+  }
+}
+
+export function buildPrebuiltReportData(
+  manifest: PrebuiltManifest | null,
+  summary: CaptureSummary | undefined
+): PrebuiltReportData | null {
+  const hasCaptures = summary && (summary.captured > 0 || summary.skipped.length > 0);
+  if (!manifest && !hasCaptures) return null;
+
+  const components: PrebuiltComponentStats[] = [];
+  let totalEntries = 0;
+  let totalBytes = 0;
+
+  if (manifest) {
+    for (const [componentId, component] of Object.entries(manifest)) {
+      let entryCount = 0;
+      let componentBytes = 0;
+      for (const entry of Object.values(component.entries)) {
+        entryCount++;
+        componentBytes += entry.bytes ?? 0;
+      }
+      components.push({ componentId, entryCount, totalBytes: componentBytes });
+      totalEntries += entryCount;
+      totalBytes += componentBytes;
+    }
+    components.sort((a, b) => a.componentId.localeCompare(b.componentId));
+  }
+
+  const skippedCount = summary?.skipped.length ?? 0;
+  const skippedReasons = (summary?.skipped ?? []).map((s) => ({
+    componentId: s.componentId,
+    route: s.routeUrlPath,
+    message: s.message,
+  }));
+
+  return { components, totalEntries, totalBytes, skippedCount, skippedReasons };
+}
+
+export function buildPrebuiltReport(data: PrebuiltReportData): string[] {
+  const lines: string[] = [];
+
+  const total = data.totalEntries + data.skippedCount;
+  lines.push(
+    `Prebuilt ${data.totalEntries}/${total} entries across ` +
+      `${data.components.length} component${data.components.length !== 1 ? 's' : ''}` +
+      (data.totalBytes > 0 ? ` (${formatSize(data.totalBytes)} total)` : '') +
+      '.' +
+      (data.skippedCount > 0 ? ` ${data.skippedCount} skipped due to errors.` : '')
+  );
+
+  if (data.components.length > 0) {
+    lines.push('');
+    const nameHeader = 'Component';
+    const entriesHeader = 'Entries';
+    const sizeHeader = 'Size';
+
+    const nameW = Math.max(
+      nameHeader.length + 2,
+      ...data.components.map((c) => c.componentId.length + 4)
+    );
+    const entriesW = Math.max(entriesHeader.length, 8);
+    const sizeW = Math.max(sizeHeader.length, 10);
+    const totalW = nameW + entriesW + sizeW + 4;
+    const sep = '─'.repeat(totalW);
+
+    lines.push(
+      `${pad(nameHeader, nameW)}  ${pad(entriesHeader, entriesW, 'left')}  ${pad(sizeHeader, sizeW, 'left')}`
+    );
+    lines.push(sep);
+
+    for (const comp of data.components) {
+      const nameStr = `  ◆ ${comp.componentId}`;
+      const entriesStr = String(comp.entryCount);
+      const sizeStr = formatSize(comp.totalBytes);
+      lines.push(
+        `${pad(nameStr, nameW)}  ${pad(entriesStr, entriesW, 'left')}  ${pad(sizeStr, sizeW, 'left')}`
+      );
+    }
+  }
+
+  if (data.skippedReasons.length > 0) {
+    lines.push('');
+    lines.push('Skipped entries:');
+    for (const s of data.skippedReasons) {
+      lines.push(`  ⚠ ${s.componentId} (${s.route}) — ${s.message}`);
+    }
+  }
+
+  return lines;
+}
+
 // ─── Bundle analysis ──────────────────────────────────────────────────────
 
 interface ChunkSize {
@@ -455,5 +572,20 @@ export function timberBuildReport(ctx: PluginContext): Plugin {
       );
       logger.info('');
     },
+
+    buildApp: {
+      order: 'post' as const,
+      async handler() {
+        if (ctx.dev || !logger) return;
+        const manifest = loadPrebuiltManifest(ctx.buildDir);
+        const prebuiltData = buildPrebuiltReportData(manifest, ctx.captureSummary);
+        if (!prebuiltData) return;
+
+        logger.info('');
+        const prebuiltLines = buildPrebuiltReport(prebuiltData);
+        for (const line of prebuiltLines) logger.info(line);
+        logger.info('');
+      },
+    },
   };
 }

package/src/plugins/cache.ts

@@ -47,6 +47,9 @@
  * referencing the same bindings — the same function, where an ID swap is
  * harmless.
  *
+ * AST helpers and the ID derivation are shared with timber-prebuilt
+ * (plugins/prebuilt.ts) via plugins/callsite-ast.ts.
+ *
  * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
  */
 
@@ -55,84 +58,20 @@ 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 MemberExpressionNode extends PositionedNode {
-  type: 'MemberExpression';
-  object: PositionedNode;
-  property: PositionedNode;
-  computed: boolean;
-}
-
-interface ProgramNode extends PositionedNode {
-  type: 'Program';
-  body: PositionedNode[];
-}
-
-interface CacheBindings {
-  /** Local names bound to `cache` via named imports (`import { cache as c }`). */
-  named: Set<string>;
-  /** Local names of namespace imports (`import * as ns`) of a cache module. */
-  namespaces: Set<string>;
-}
-
-/**
- * Find the local binding name(s) for `cache` imported from the cache module —
- * both named imports and namespace imports (TIM-1054).
- */
-function findCacheBindings(program: ProgramNode): CacheBindings {
-  const named = new Set<string>();
-  const namespaces = 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 === 'ImportNamespaceSpecifier') {
-        namespaces.add(spec.local.name);
-        continue;
-      }
-      if (spec.type !== 'ImportSpecifier') continue;
-      const importedName = spec.imported?.name ?? spec.local.name;
-      if (importedName === 'cache') {
-        named.add(spec.local.name);
-      }
-    }
-  }
-  return { named, namespaces };
-}
+import {
+  CACHE_MODULE_SOURCES,
+  findCallSites,
+  findImportBindings,
+  generateStableCallsiteId,
+} from './callsite-ast.js';
+import type {
+  CallExpressionNode,
+  IdentifierNode,
+  ImportBindings,
+  MemberExpressionNode,
+  PositionedNode,
+  ProgramNode,
+} from './callsite-ast.js';
 
 /**
  * Is this callee a reference to the imported `cache` function — either a bare
@@ -140,7 +79,7 @@ function findCacheBindings(program: ProgramNode): CacheBindings {
  * Computed access (`ns['cache']`) is deliberately not matched; it falls back
  * to the runtime fnId derivation.
  */
-function isCacheCallee(callee: PositionedNode, bindings: CacheBindings): boolean {
+function isCacheCallee(callee: PositionedNode, bindings: ImportBindings): boolean {
   if (callee.type === 'Identifier') {
     return bindings.named.has((callee as IdentifierNode).name);
   }
@@ -158,54 +97,8 @@ function isCacheCallee(callee: PositionedNode, bindings: CacheBindings): boolean
 }
 
 /**
- * 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: CacheBindings,
-  results: CallExpressionNode[]
-): void {
-  if (node.type === 'CallExpression') {
-    const call = node as unknown as CallExpressionNode;
-    if (call.arguments.length === 2 && isCacheCallee(call.callee, cacheBindings)) {
-      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, the source text of the
- * enclosing top-level statement, the source text of the cache(...) call
- * expression, and an occurrence index among fully byte-identical
- * (statement, call) pairs in the same file.
- *
- * The ID is deterministic and:
- * - Stable across cold starts AND across builds/deploys for unchanged calls —
- *   inserting, deleting, or reordering other cache() calls does not affect it
- * - Unique across different modules (relPath component)
- * - Unique across distinct cache() calls within a module (statement + span
- *   hashes), with fully identical duplicates disambiguated by source-order
- *   occurrence
- * - Fresh when the wrapped fn, opts, or enclosing statement change, which
- *   intentionally invalidates the old persisted entries
+ * Generate a stable callsite ID for a cache() call. See callsite-ast.ts for
+ * the derivation properties.
  */
 function generateStableId(
   relativeModulePath: string,
@@ -213,8 +106,12 @@ function generateStableId(
   callSpanText: string,
   occurrence: number
 ): string {
-  return fnv1aHash(
-    `${relativeModulePath}:cache:${fnv1aHash(statementText)}:${fnv1aHash(callSpanText)}:${occurrence}`
+  return generateStableCallsiteId(
+    relativeModulePath,
+    'cache',
+    statementText,
+    callSpanText,
+    occurrence
   );
 }
 
@@ -234,7 +131,7 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
         return;
       }
 
-      const cacheBindings = findCacheBindings(program);
+      const cacheBindings = findImportBindings(program, CACHE_MODULE_SOURCES, 'cache');
       if (cacheBindings.named.size === 0 && cacheBindings.namespaces.size === 0) return;
 
       // Collect call sites per top-level statement so each call carries its
@@ -242,7 +139,11 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
       const callSites: Array<{ call: CallExpressionNode; stmt: PositionedNode }> = [];
       for (const stmt of program.body) {
         const calls: CallExpressionNode[] = [];
-        findCacheCallSites(stmt, cacheBindings, calls);
+        findCallSites(
+          stmt,
+          (call) => call.arguments.length === 2 && isCacheCallee(call.callee, cacheBindings),
+          calls
+        );
         for (const call of calls) callSites.push({ call, stmt });
       }
       if (callSites.length === 0) return;