@timber-js/app 0.2.0-alpha.57 → 0.2.0-alpha.58

package/src/index.ts

@@ -15,6 +15,7 @@ import { timberStaticBuild } from './plugins/static-build';
 import { timberServerActionExports } from './plugins/server-action-exports';
 import { timberBuildManifest } from './plugins/build-manifest';
 import { timberDevLogs } from './plugins/dev-logs';
+import { timberDevBrowserLogs } from './plugins/dev-browser-logs';
 import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
 import { clientChunkGroup } from './plugins/client-chunks';
@@ -102,6 +103,21 @@ export interface TimberUserConfig {
    * See design/02-rendering-pipeline.md §"Streaming Constraints".
    */
   renderTimeoutMs?: number;
+  /**
+   * Forward browser console output to the server terminal in dev mode.
+   *
+   * Sets the minimum log level to forward:
+   * - `'error'` — only `console.error`
+   * - `'warn'` — `console.error` + `console.warn` (default)
+   * - `'info'` — `console.error` + `console.warn` + `console.info`
+   * - `'none'` — disabled
+   *
+   * Does not intercept `console.log` or `console.debug` (too noisy).
+   * No effect in production builds.
+   *
+   * See TIM-513.
+   */
+  devBrowserLogs?: 'error' | 'warn' | 'info' | 'none';
   /** Dev-mode options. These have no effect in production builds. */
   dev?: {
     /** Threshold in ms to highlight slow phases in dev logging output. Default: 200. */
@@ -644,6 +660,7 @@ 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/params/define.ts

@@ -15,6 +15,33 @@
 
 import type { Codec } from '#/codec.js';
 
+// ---------------------------------------------------------------------------
+// Server-only ALS reference for .load()
+// ---------------------------------------------------------------------------
+
+// Same pattern as search-params: eagerly registered at server startup
+// to avoid dynamic imports that lose ALS context. See TIM-523.
+let _rawSegmentParams: (() => Promise<Record<string, string | string[]>>) | undefined;
+
+/**
+ * Register the rawSegmentParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setRawSegmentParamsFn(fn: () => Promise<Record<string, string | string[]>>): void {
+  _rawSegmentParams = fn;
+}
+
+function getRawSegmentParams(): Promise<Record<string, string | string[]>> {
+  if (!_rawSegmentParams) {
+    throw new Error(
+      '[timber] segmentParams.load() is only available on the server. ' +
+        'Use useSegmentParams() on the client.'
+    );
+  }
+  return _rawSegmentParams();
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -39,6 +66,25 @@ export interface ParamsDefinition<T extends Record<string, unknown>> {
   /** Serialize typed values back to strings for URL construction. */
   serialize(values: T): Record<string, string>;
 
+  /**
+   * Load typed segment params from the current request context (ALS).
+   *
+   * Server-only. Reads rawSegmentParams() from ALS and coerces through
+   * this definition's codecs, returning fully typed params.
+   *
+   * ```ts
+   * // app/products/[id]/params.ts
+   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })
+   *
+   * // app/products/[id]/page.tsx
+   * import { segmentParams } from './params'
+   * export default async function Page() {
+   *   const { id } = await segmentParams.load() // id: number
+   * }
+   * ```
+   */
+  load(): Promise<T>;
+
   /** Read-only codec map. */
   codecs: { [K in keyof T]: Codec<T[K]> };
 }
@@ -250,9 +296,23 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
     return result;
   }
 
+  // ---- load ----
+  // ALS-backed: reads rawSegmentParams() from the current request context
+  // and parses through codecs. Server-only — throws on client.
+  async function load(): Promise<T> {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] segmentParams.load() is server-only. ' + 'Use useSegmentParams() on the client.'
+      );
+    }
+    const raw = await getRawSegmentParams();
+    return parse(raw);
+  }
+
   const definition: ParamsDefinition<T> = {
     parse,
     serialize,
+    load,
     codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },
   };
 

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

@@ -0,0 +1,274 @@
+/**
+ * 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') return;
+
+      // 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/server/als-registry.ts

@@ -21,6 +21,7 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
 // ─── Request Context ──────────────────────────────────────────────────────
 // Used by: request-context.ts (headers(), cookies(), searchParams())
@@ -64,6 +65,12 @@ export interface RequestContextStore {
   flushed: boolean;
   /** Whether the current context allows cookie mutation. */
   mutableContext: boolean;
+  /**
+   * Dev-only: getter for the current request's RSC debug components.
+   * Set by renderRoute() so onPipelineError can include component tree
+   * context for render-phase errors without module-level shared state.
+   */
+  debugComponentsGetter?: () => DebugComponentEntry[];
 }
 
 /** A single outgoing cookie entry in the cookie jar. */

package/src/server/deny-renderer.ts

@@ -29,6 +29,7 @@ import type { NavContext } from './ssr-entry.js';
 import { flightInitScript } from './flight-scripts.js';
 import type { ClientBootstrapConfig } from './html-injectors.js';
 import type { Metadata } from './types.js';
+import { teeWithErrorPropagation } from './stream-utils.js';
 
 /** RSC content type for client navigation payload requests. */
 const RSC_CONTENT_TYPE = 'text/x-component';
@@ -171,7 +172,7 @@ export async function renderDenyPage(
     debugChannel: createDebugChannelSink(),
   });
 
-  const [ssrStream, inlineStream] = rscStream.tee();
+  const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
 
   const navContext: NavContext = {
     pathname: new URL(req.url).pathname,

package/src/server/request-context.ts

@@ -13,6 +13,7 @@
 import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
 import { isDebug } from './debug.js';
 import { _setRawSearchParamsFn } from '#/search-params/define.js';
+import { _setRawSegmentParamsFn } from '#/params/define.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -185,6 +186,11 @@ export function rawSearchParams(): Promise<URLSearchParams> {
 // breaking rawSearchParams() in parallel slot pages. See TIM-523.
 _setRawSearchParamsFn(rawSearchParams);
 
+// Eagerly register rawSegmentParams with the params module so
+// segmentParams.load() can call it synchronously without a dynamic import.
+// Same pattern as search params — dynamic imports lose ALS context. See TIM-523.
+_setRawSegmentParamsFn(rawSegmentParams);
+
 /**
  * Returns a Promise resolving to the current request's coerced segment params.
  *