@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

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/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 '../index.js';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',

package/src/plugins/dev-browser-logs.ts

@@ -0,0 +1,288 @@
+/**
+ * timber-dev-browser-logs — Forwards browser console output to the server terminal.
+ *
+ * Injects a small inline script in dev mode that intercepts browser
+ * `console.error`, `console.warn`, and `console.info`, then forwards
+ * messages to the server via Vite's HMR WebSocket.
+ *
+ * The server-side listener formats and prints the messages with color-coded
+ * prefixes: [browser:error], [browser:warn], [browser:info].
+ *
+ * Dev-only: this plugin only runs during `vite dev`.
+ * No runtime overhead in production.
+ *
+ * See TIM-513 for design context.
+ * See design/18-build-system.md §"Dev Server" for sub-plugin architecture.
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import type { PluginContext } from '../index.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/** Log levels forwarded from the browser. */
+export type BrowserLogLevel = 'error' | 'warn' | 'info';
+
+/** Configuration value for devBrowserLogs in timber.config.ts. */
+export type DevBrowserLogsConfig = BrowserLogLevel | 'none' | undefined;
+
+/**
+ * Payload sent from browser to server via Vite's HMR WebSocket.
+ * Kept small — truncated before sending.
+ */
+export interface BrowserLogPayload {
+  level: BrowserLogLevel;
+  /** Serialized message string. */
+  message: string;
+  /** Error stack trace, if the first argument was an Error. */
+  stack: string | null;
+  /** Source URL and line number, if available. */
+  source: string | null;
+  /** Timestamp in ms (Date.now()) from the browser. */
+  timestamp: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────
+
+/** Max message size in bytes before truncation. */
+const MAX_MESSAGE_BYTES = 2048;
+
+/** HMR event name for browser→server log forwarding. */
+const HMR_EVENT = 'timber:browser-log';
+
+/** ANSI color codes for terminal output. */
+const COLORS = {
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m',
+} as const;
+
+/** Level severity ordering for threshold comparison. */
+const LEVEL_SEVERITY: Record<BrowserLogLevel | 'none', number> = {
+  none: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+// ─── Formatting ──────────────────────────────────────────────────────────
+
+/**
+ * Format a browser log payload for server terminal output.
+ *
+ * Produces color-coded output like:
+ *   [browser:error] Uncaught TypeError: x is not a function
+ *     at App (app.tsx:10:5)
+ *   [browser:warn] Deprecation warning (app/page.tsx:42:12)
+ */
+export function formatBrowserLog(payload: BrowserLogPayload): string {
+  const { level, message, stack, source } = payload;
+
+  // Color-coded prefix
+  const color = level === 'error' ? COLORS.red : level === 'warn' ? COLORS.yellow : COLORS.blue;
+  const prefix = `${color}[browser:${level}]${COLORS.reset}`;
+
+  // Source suffix
+  const sourceSuffix = source ? ` ${COLORS.dim}(${source})${COLORS.reset}` : '';
+
+  let output = `${prefix} ${message}${sourceSuffix}`;
+
+  // Append stack trace indented
+  if (stack) {
+    const indented = stack
+      .split('\n')
+      .map((line) => `  ${COLORS.dim}${line}${COLORS.reset}`)
+      .join('\n');
+    output += `\n${indented}`;
+  }
+
+  return output;
+}
+
+// ─── Level Filtering ─────────────────────────────────────────────────────
+
+/**
+ * Check if a log at `level` should be forwarded given the configured threshold.
+ *
+ * The threshold acts as a minimum severity:
+ * - 'error' → only errors
+ * - 'warn' → errors + warnings
+ * - 'info' → errors + warnings + info
+ * - 'none' → nothing
+ */
+export function shouldForwardLevel(
+  level: BrowserLogLevel,
+  threshold: BrowserLogLevel | 'none'
+): boolean {
+  if (threshold === 'none') return false;
+  return LEVEL_SEVERITY[level] >= LEVEL_SEVERITY[threshold];
+}
+
+// ─── Truncation ──────────────────────────────────────────────────────────
+
+/**
+ * Truncate a message to `maxBytes` to avoid flooding the terminal.
+ * Appends a suffix indicating how many bytes were dropped.
+ */
+export function truncateMessage(message: string, maxBytes: number): string {
+  if (message.length <= maxBytes) return message;
+
+  const truncated = message.slice(0, maxBytes);
+  const droppedBytes = message.length - maxBytes;
+  return `${truncated}… [truncated ${droppedBytes} bytes]`;
+}
+
+// ─── Client Injection Script ─────────────────────────────────────────────
+
+/**
+ * Generate the inline script injected into the browser in dev mode.
+ *
+ * This script:
+ * 1. Saves references to the original console methods
+ * 2. Wraps `console.error`, `console.warn`, `console.info`
+ * 3. Calls the original first (browser devtools still work)
+ * 4. Serializes and forwards via `import.meta.hot.send()`
+ * 5. Truncates messages to MAX_MESSAGE_BYTES
+ *
+ * The script is minimal and self-contained — no imports, no dependencies.
+ */
+export function generateClientScript(threshold: BrowserLogLevel | 'none'): string {
+  if (threshold === 'none') return '';
+
+  // Only intercept levels that meet the threshold
+  const levels: BrowserLogLevel[] = ['error', 'warn', 'info'].filter((l) =>
+    shouldForwardLevel(l as BrowserLogLevel, threshold)
+  ) as BrowserLogLevel[];
+
+  if (levels.length === 0) return '';
+
+  return `
+(function() {
+  if (!import.meta.hot) return;
+  var MAX_BYTES = ${MAX_MESSAGE_BYTES};
+  var levels = ${JSON.stringify(levels)};
+  var originals = {};
+
+  function serialize(arg) {
+    if (arg === null) return 'null';
+    if (arg === undefined) return 'undefined';
+    if (arg instanceof Error) return arg.stack || arg.message || String(arg);
+    if (typeof arg === 'object') {
+      try { return JSON.stringify(arg); } catch(e) { return String(arg); }
+    }
+    return String(arg);
+  }
+
+  function truncate(s) {
+    if (s.length <= MAX_BYTES) return s;
+    return s.slice(0, MAX_BYTES) + '... [truncated ' + (s.length - MAX_BYTES) + ' bytes]';
+  }
+
+  levels.forEach(function(level) {
+    originals[level] = console[level];
+    console[level] = function() {
+      originals[level].apply(console, arguments);
+      try {
+        var args = Array.prototype.slice.call(arguments);
+        var firstArg = args[0];
+        var stack = null;
+        var source = null;
+
+        if (firstArg instanceof Error) {
+          stack = firstArg.stack || null;
+          source = null;
+        }
+
+        var message = args.map(serialize).join(' ');
+        message = truncate(message);
+
+        import.meta.hot.send('${HMR_EVENT}', {
+          level: level,
+          message: message,
+          stack: stack,
+          source: source,
+          timestamp: Date.now()
+        });
+      } catch(e) {
+        // Never let log forwarding break the page
+      }
+    };
+  });
+})();
+`.trim();
+}
+
+// ─── Plugin ──────────────────────────────────────────────────────────────
+
+/**
+ * Create the timber-dev-browser-logs Vite plugin.
+ *
+ * - `configureServer`: Listens for HMR messages and prints them to the terminal
+ * - `transformIndexHtml`: Injects the client-side interception script
+ *
+ * Only active during `vite dev` (apply: 'serve').
+ */
+export function timberDevBrowserLogs(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-dev-browser-logs',
+    apply: 'serve',
+
+    configureServer(server: ViteDevServer) {
+      const threshold = ctx.config.devBrowserLogs ?? 'warn';
+      if (threshold === 'none') {
+        // Clear any stale script from a prior server instance (e.g. HMR reconfigure)
+        delete (globalThis as Record<string, unknown>).__timber_dev_browser_log_script;
+        return;
+      }
+
+      // Register the client injection script on globalThis so the RSC entry
+      // can include it in headHtml for all Timber route responses.
+      // transformIndexHtml only runs for Vite's index.html fallback, not
+      // for responses served by createTimberMiddleware (TIM-575).
+      const script = generateClientScript(threshold);
+      if (script) {
+        (globalThis as Record<string, unknown>).__timber_dev_browser_log_script =
+          `<script type="module">${script}</script>`;
+      }
+
+      // Listen for browser log messages via HMR WebSocket
+      server.hot.on(HMR_EVENT, (payload: BrowserLogPayload) => {
+        try {
+          // Validate level
+          if (!shouldForwardLevel(payload.level, threshold)) return;
+
+          // Truncate server-side too (defense in depth)
+          payload.message = truncateMessage(payload.message, MAX_MESSAGE_BYTES);
+
+          const formatted = formatBrowserLog(payload);
+
+          // Use the correct console method for the log level
+          if (payload.level === 'error') {
+            process.stderr.write(formatted + '\n');
+          } else {
+            process.stdout.write(formatted + '\n');
+          }
+        } catch {
+          // Never let log forwarding crash the server
+        }
+      });
+    },
+
+    transformIndexHtml() {
+      const threshold = ctx.config.devBrowserLogs ?? 'warn';
+      const script = generateClientScript(threshold);
+      if (!script) return [];
+
+      return [
+        {
+          tag: 'script',
+          attrs: { type: 'module' },
+          children: script,
+          injectTo: 'head' as const,
+        },
+      ];
+    },
+  };
+}

package/src/plugins/dev-error-overlay.ts

@@ -180,6 +180,63 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
   return lines.join('\n');
 }
 
+// ─── RSC Debug Context ──────────────────────────────────────────────────────
+
+/**
+ * Component info extracted from the RSC debug channel.
+ * Contains only names, environments, and stack frames — never source code.
+ */
+export interface RscDebugComponentInfo {
+  name: string;
+  env: string | null;
+  stack: unknown[] | null;
+}
+
+/**
+ * Format RSC debug component info into a readable string for the overlay.
+ *
+ * Renders the server component tree that was active when an error occurred,
+ * including component names and source locations from stack frames. This
+ * gives developers visibility into which server components were rendering
+ * without exposing source code.
+ *
+ * Returns an empty string if no components are provided.
+ */
+export function formatRscDebugContext(components: RscDebugComponentInfo[]): string {
+  if (!components || components.length === 0) return '';
+
+  // Deduplicate by name — the debug channel may emit the same component
+  // multiple times (e.g., when re-rendered or when multiple instances exist).
+  const seen = new Set<string>();
+  const unique: RscDebugComponentInfo[] = [];
+  for (const c of components) {
+    if (!seen.has(c.name)) {
+      seen.add(c.name);
+      unique.push(c);
+    }
+  }
+
+  const lines: string[] = ['Server Component Tree:'];
+  for (let i = 0; i < unique.length; i++) {
+    const c = unique[i]!;
+    const indent = '  '.repeat(i + 1);
+    const envLabel = c.env ? ` [${c.env}]` : '';
+
+    // Extract file location from stack frames if available
+    let locStr = '';
+    if (c.stack && c.stack.length > 0) {
+      const frame = c.stack[0] as [string, string, number, number] | undefined;
+      if (Array.isArray(frame) && frame.length >= 3) {
+        locStr = ` (${frame[1]}:${frame[2]})`;
+      }
+    }
+
+    lines.push(`${indent}${c.name}${envLabel}${locStr}`);
+  }
+
+  return lines.join('\n');
+}
+
 // ─── Overlay Integration ────────────────────────────────────────────────────
 
 /**
@@ -188,13 +245,19 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
  * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
  * then sends the error via `server.hot.send()` for the browser overlay.
  *
+ * When `rscDebugComponents` is provided (dev mode only), the server
+ * component tree context is appended to the error message. This helps
+ * developers identify which server component caused the error without
+ * exposing source code.
+ *
  * The dev server remains running — errors are handled, not fatal.
  */
 export function sendErrorToOverlay(
   server: ViteDevServer,
   error: Error,
   phase: ErrorPhase,
-  projectRoot: string
+  projectRoot: string,
+  rscDebugComponents?: RscDebugComponentInfo[]
 ): void {
   // Fix stack trace to use source-mapped positions
   server.ssrFixStacktrace(error);
@@ -212,6 +275,12 @@ export function sendErrorToOverlay(
     message = `${error.message}\n\nComponent Stack:\n${componentStack.trim()}`;
   }
 
+  // Append RSC debug context if available (dev mode only)
+  const debugContext = formatRscDebugContext(rscDebugComponents ?? []);
+  if (debugContext) {
+    message = `${message}\n\n${debugContext}`;
+  }
+
   // Send to browser via Vite's error overlay protocol
   try {
     server.hot.send({

package/src/plugins/dev-logs.ts

@@ -13,7 +13,7 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../index.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 

package/src/plugins/dev-server.ts

@@ -15,10 +15,10 @@
 import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
-import { setViteServer } from '#/server/dev-warnings.js';
+import type { PluginContext } from '../index.js';
+import { setViteServer } from '../server/dev-warnings.js';
 import { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
-import { compressResponse } from '#/server/compress.js';
+import { compressResponse } from '../server/compress.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -161,12 +161,26 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
 
       // Wire pipeline errors into the browser error overlay.
       // setDevPipelineErrorHandler is only defined in dev (rsc-entry.ts exports it).
+      // The handler receives optional RSC debug component data (component names,
+      // environments, stack frames) from the Flight debug channel for render errors.
       const setHandler = rscModule.setDevPipelineErrorHandler as
-        | ((fn: (error: Error, phase: string) => void) => void)
+        | ((
+            fn: (
+              error: Error,
+              phase: string,
+              debugComponents?: Array<{ name: string; env: string | null; stack: unknown[] | null }>
+            ) => void
+          ) => void)
         | undefined;
       if (typeof setHandler === 'function') {
-        setHandler((error) => {
-          sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
+        setHandler((error, _phase, debugComponents) => {
+          sendErrorToOverlay(
+            server,
+            error,
+            classifyErrorPhase(error, projectRoot),
+            projectRoot,
+            debugComponents
+          );
         });
       }
     } catch (error) {
@@ -191,8 +205,20 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Convert Node IncomingMessage → Web Request
       const webRequest = toWebRequest(req);
 
-      // Run the full pipeline
-      const webResponse = await handler(webRequest);
+      // Check for a platform-specific request wrapper (e.g., Cloudflare
+      // dev bindings). The cloudflareDevBindings() plugin stores a wrapper
+      // function on the server instance using a well-known Symbol. The
+      // wrapper runs the handler inside an ALS context so platform APIs
+      // like getCloudflareBindings() work during dev.
+      // See design/35-cloudflare-primitives.md §"Dev Experience".
+      const wrapper = (server as any)[Symbol.for('timber:dev-request-wrapper')] as
+        | (<T>(fn: () => T) => T)
+        | undefined;
+
+      // Run the full pipeline (wrapped if a platform dev plugin is active)
+      const webResponse = wrapper
+        ? await wrapper(() => handler(webRequest))
+        : await handler(webRequest);
 
       // Compress the response if the client supports it.
       // In dev mode, compression is always enabled for parity with production.
@@ -317,6 +343,17 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
   nodeRes.flushHeaders();
 
   const reader = webResponse.body.getReader();
+
+  // Cancel the reader when the client disconnects. This causes any pending
+  // reader.read() to reject, breaking the pump loop. Critical for SSE and
+  // other infinite streams — without this, disconnected clients leak readers.
+  let clientDisconnected = false;
+  const onClose = () => {
+    clientDisconnected = true;
+    reader.cancel('Client disconnected').catch(() => {});
+  };
+  nodeRes.on('close', onClose);
+
   try {
     while (true) {
       const { done, value } = await reader.read();
@@ -325,9 +362,18 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
       // don't need back-pressure here — just keep pushing chunks.
       nodeRes.write(value);
     }
+  } catch (err) {
+    // reader.cancel() from the close handler causes read() to reject.
+    // This is expected on client disconnect — not an error.
+    if (!clientDisconnected) {
+      throw err;
+    }
   } finally {
+    nodeRes.off('close', onClose);
     reader.releaseLock();
-    nodeRes.end();
+    if (!nodeRes.writableEnded) {
+      nodeRes.end();
+    }
   }
 }