@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/client/ssr-data.ts

@@ -1,17 +1,20 @@
 /**
  * SSR Data — per-request state for client hooks during server-side rendering.
  *
- * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),
- * so the RSC environment's request-context ALS is not visible to SSR modules.
- * This module provides getter/setter functions that ssr-entry.ts uses to
- * populate per-request data for React's render.
+ * `useCookie()` and `<Link preserveSearchParams>` have no React context to
+ * read their request values from during SSR, so the SSR entry hands them
+ * the request's cookies and search string through this module.
+ * `useSearchParams()` reads NavigationContext and uses getSsrData() only to
+ * detect that it is rendering on the server. Route
+ * params do not travel here — client components read them from
+ * `ParamsContext`, decoded from the payload root.
  *
- * Request isolation: On the server, ssr-entry.ts registers an ALS-backed
- * provider via registerSsrDataProvider(). getSsrData() reads from the ALS
- * store, ensuring correct per-request data even when Suspense boundaries
- * resolve asynchronously across concurrent requests. The module-level
- * setSsrData/clearSsrData functions are kept as a fallback for tests
- * and environments without ALS.
+ * Request isolation: ssr-entry.ts registers an ALS-backed provider via
+ * registerSsrDataProvider(), so getSsrData() reads the current request's
+ * store even when Suspense boundaries resolve asynchronously across
+ * concurrent requests. There is no module-level fallback: outside an SSR
+ * render (in the browser, or before the provider is registered) there is no
+ * request, and getSsrData() returns undefined.
  *
  * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only
  * APIs, as it's imported by 'use client' hooks that are bundled for the browser.
@@ -22,20 +25,11 @@
  * See design/18-build-system.md §"Singleton State Registry"
  */
 
-import {
-  ssrDataProvider,
-  currentSsrData,
-  _setSsrDataProvider,
-  _setCurrentSsrData,
-} from './state.ts';
-import type { CoercedParams } from '../shared/param-value.ts';
-import type { SlotParamsRecord } from '../shared/slot-params.ts';
+import { ssrDataProvider, _setSsrDataProvider } from './state.ts';
 
 // ─── Types ────────────────────────────────────────────────────────
 
 export interface SsrData {
-  /** The request's URL pathname (e.g. '/dashboard/settings') */
-  pathname: string;
   /**
    * The request's raw app-visible query string (`''` or `?…`), matching what
    * `window.location.search` will hold after hydration. The raw string is
@@ -46,28 +40,6 @@ export interface SsrData {
   search: string;
   /** The request's cookies as name→value pairs */
   cookies: Map<string, string>;
-  /** The request's route params (e.g. { id: '123' }) */
-  params: CoercedParams;
-  /**
-   * Per-slot params keyed by slot tree path, absent when the request rendered
-   * no slot with params of its own (TIM-1285).
-   */
-  slotParams?: SlotParamsRecord;
-  /**
-   * Mutable reference to NavContext for error boundary → pipeline communication.
-   *
-   * When TimberErrorBoundary catches a DenySignal during SSR, it:
-   * 1. Sets `statusCode` to the deny status (e.g., 403) — so the HTTP
-   *    Response has the correct status code without a re-render.
-   * 2. Sets `_denyHandledByBoundary = true` — so the pipeline skips
-   *    the redundant renderDenyPage() re-render.
-   *
-   * This runs synchronously during Fizz rendering, BEFORE onShellReady,
-   * so the status code is committed before any bytes are sent.
-   *
-   * See TIM-664, design/04-authorization.md §"React.cache Scope in Deny/Error Re-renders"
-   */
-  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };
 }
 
 // ─── ALS-Backed Provider ─────────────────────────────────────────
@@ -87,53 +59,20 @@ export interface SsrData {
 // See timber-shims plugin resolveId for details.
 
 /**
- * Register an ALS-backed SSR data provider. Called once at module load
- * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.
- *
- * When registered, getSsrData() reads from the provider (ALS store)
- * instead of module-level state, ensuring correct isolation for
- * concurrent requests with streaming Suspense.
+ * Register the SSR data provider. Called once at module load by
+ * ssr-entry.ts to wire up per-request data via AsyncLocalStorage; tests
+ * register their own provider (and `undefined` to reset).
  */
-export function registerSsrDataProvider(provider: () => SsrData | undefined): void {
+export function registerSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {
   _setSsrDataProvider(provider);
 }
 
-// ─── Module-Level Fallback ────────────────────────────────────────
-//
-// Used by tests and as a fallback when no ALS provider is registered.
-
-/**
- * Set the SSR data for the current request via module-level state.
- *
- * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.
- * This function is retained for tests and as a fallback.
- */
-export function setSsrData(data: SsrData): void {
-  _setCurrentSsrData(data);
-}
-
-/**
- * Clear the SSR data after rendering completes.
- *
- * In production, ALS scope handles cleanup automatically.
- * This function is retained for tests and as a fallback.
- */
-export function clearSsrData(): void {
-  _setCurrentSsrData(undefined);
-}
-
 /**
  * Read the current request's SSR data. Returns undefined when called
  * outside an SSR render (i.e. on the client after hydration).
  *
- * Prefers the ALS-backed provider when registered (server-side),
- * falling back to module-level state (tests, legacy).
- *
  * Used by client hooks' server snapshot functions.
  */
 export function getSsrData(): SsrData | undefined {
-  if (ssrDataProvider) {
-    return ssrDataProvider();
-  }
-  return currentSsrData;
+  return ssrDataProvider?.();
 }

package/src/client/state.ts

@@ -34,8 +34,8 @@ export function _setGlobalRouter(router: RouterInstance | null): void {
 // ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────
 
 /**
- * ALS-backed SSR data provider. When registered, getSsrData() reads from
- * this function (ALS store) instead of module-level currentSsrData.
+ * ALS-backed SSR data provider, registered by the SSR entry. getSsrData()
+ * reads through it; unset in the browser.
  */
 export let ssrDataProvider: (() => SsrData | undefined) | undefined;
 
@@ -43,13 +43,6 @@ export function _setSsrDataProvider(provider: (() => SsrData | undefined) | unde
   ssrDataProvider = provider;
 }
 
-/** Fallback SSR data for tests and environments without ALS. */
-export let currentSsrData: SsrData | undefined;
-
-export function _setCurrentSsrData(data: SsrData | undefined): void {
-  currentSsrData = data;
-}
-
 // ─── Search Params Cache (from use-search-params.ts) ────────────────────────
 
 /** Cached search string — avoids reparsing when URL hasn't changed. */

package/src/client/use-pathname.ts

@@ -6,7 +6,7 @@
  *
  * One unconditional read of NavigationContext, on every side (TIM-1425):
  *
- * - In the browser, the provider wraps the RSC payload in renderRoot(), so
+ * - In the browser, the provider wraps the RSC payload in the router's `renderTree`, so
  *   the pathname updates in the same render pass as the new tree.
  * - During SSR, the wrapper chain mounts the same provider with the request's
  *   pathname (TIM-1424), so this is the identical code path — no ALS read,

package/src/config-types.ts

@@ -136,7 +136,8 @@ export interface TimberUserConfig {
    *   browser DevTools useful timing without internal details.
    * - `false` — no Server-Timing header at all.
    *
-   * Default: `'detailed'` in dev, `'total'` in production.
+   * Default: `'total'` in dev and production. Detailed mode logs a
+   * stream-lifecycle line per request, so it is opt-in everywhere.
    *
    * This is separate from `debug` / `TIMBER_DEBUG` — it's an intentional
    * decision to expose timing data to clients, not a side effect of debug

package/src/config-validation.ts

@@ -10,6 +10,7 @@
 
 import { createRequire } from 'node:module';
 import type { TimberUserConfig } from './config-types.ts';
+import { DEFAULT_RENDER_TIMEOUT_MS, RENDER_TIMEOUT_CEILING_MS } from './server/render-timeout.ts';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -126,7 +127,7 @@ export function validateConfig(config: TimberUserConfig): ConfigError[] {
         field: 'renderTimeoutMs',
         message: `renderTimeoutMs must be a non-negative number (got ${JSON.stringify(config.renderTimeoutMs)}).`,
         value: config.renderTimeoutMs,
-        suggestion: 'Use renderTimeoutMs: 30000 (default). Setting 0 uses a 120s safety ceiling.',
+        suggestion: `Use renderTimeoutMs: ${DEFAULT_RENDER_TIMEOUT_MS} (default). Setting 0 uses a ${RENDER_TIMEOUT_CEILING_MS / 1000}s safety ceiling.`,
       });
     }
   }

package/src/dev-tools/dev-page-shell.ts

@@ -31,6 +31,24 @@ export interface DevErrorHmrOptions {
   token?: string;
 }
 
+/**
+ * Hooks the dev server hands the RSC environment, which cannot read the
+ * Vite server itself (separate module graph). The RSC entry exports
+ * `setDevHooks()`; the dev server calls it after importing the entry.
+ *
+ * Declared here, not in the RSC entry, so the dev-server plugin can name
+ * the type without pulling the RSC entry into its type graph.
+ */
+export interface DevHooks {
+  /** Forwards a pipeline error to the browser error overlay. */
+  onPipelineError?: (error: Error, phase: string) => void;
+  /**
+   * The resolved HMR endpoint for the auto-reload WebSocket on the dev 404
+   * page and the fallback error page (TIM-1067).
+   */
+  hmrOptions?: DevErrorHmrOptions;
+}
+
 /**
  * Extract HMR connection options from a Vite resolved config.
  * Used by the dev server to pass HMR config to the dev page generators

package/src/dev-tools/index.ts

@@ -28,11 +28,9 @@ export {
 // Error overlay (Vite integration)
 export {
   sendErrorToOverlay,
-  fixErrorStacktrace,
   classifyErrorPhase,
   extractComponentStack,
   parseFirstAppFrame,
-  calculateModuleRunnerOffset,
   formatTerminalError,
   PHASE_LABELS,
   type ErrorPhase,

package/src/dev-tools/instrumentation.ts

@@ -8,13 +8,20 @@
  * 2. Span processing: collects completed spans per-request and drives
  *    dev log output when the root span ends.
  *
- * Only activated in dev mode — zero overhead in production.
+ * Activated in dev, and in production only when TIMBER_DEBUG is set
+ * (design/13-security.md §"Debug Flag Security Boundary"); otherwise never
+ * loaded.
  *
  * Design ref: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
  */
 
 import * as api from '@opentelemetry/api';
-import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import {
+  BasicTracerProvider,
+  type SpanProcessor,
+  type ReadableSpan,
+} from '@opentelemetry/sdk-trace-base';
 import type { Span, Context } from '@opentelemetry/api';
 import {
   formatSpanTree,
@@ -211,3 +218,44 @@ export class DevSpanProcessor implements SpanProcessor {
     // Nothing to flush — output happens synchronously in onEnd.
   }
 }
+
+// ─── SDK Registration ───────────────────────────────────────────────────────
+
+/**
+ * Register a context manager and a tracer provider feeding DevSpanProcessor
+ * as the OTEL globals. Called once by initDevTracing().
+ *
+ * The SDK packages are imported statically here, and this module is the one
+ * initDevTracing() loads dynamically. A dynamic import of the CJS-only
+ * @opentelemetry/context-async-hooks bundles into a chunk whose namespace
+ * holds the exports on `default`, and loaders that rewrite such namespaces
+ * (tsx exposes the named exports and drops `default`) hand back no
+ * constructor at all (TIM-1554). A static import calls the bundled CJS
+ * factory directly and has no namespace to rewrite.
+ */
+export function registerDevTracing(config: DevLoggerConfig): void {
+  // Construct everything before registering anything: a constructor that
+  // throws must leave no half-registered global state behind.
+
+  // A minimal TracerProvider with our DevSpanProcessor. If the user also
+  // configures an SDK in register(), their provider will coexist — the
+  // global provider set last wins for new tracers, but our processor
+  // captures all spans from the timber.js tracer.
+  const provider = new BasicTracerProvider({
+    spanProcessors: [new DevSpanProcessor(config)],
+  });
+
+  // A context manager so OTEL can propagate the active span across async
+  // boundaries. Without this, startActiveSpan can't make spans "active" —
+  // child spans get random trace IDs and getActiveSpan() returns undefined.
+  const contextManager = new AsyncLocalStorageContextManager();
+
+  contextManager.enable();
+  api.context.setGlobalContextManager(contextManager);
+  api.trace.setGlobalTracerProvider(provider);
+
+  // Fetch spans nest under the active component span in the dev log tree.
+  // Patched here, not by the caller, so one guarded import of this module
+  // covers all of tracing setup (TIM-1554).
+  instrumentDevFetch();
+}

package/src/dev-tools/overlay.ts

@@ -4,51 +4,15 @@
  * Integrates with Vite's built-in error overlay (`server.hot.send`) rather
  * than implementing a custom overlay.
  *
- * Stack trace source-mapping uses the correct Vite environment module graph:
- * RSC errors use `server.environments.rsc.moduleGraph`, SSR/other errors use
- * `server.environments.ssr.moduleGraph`. `server.ssrFixStacktrace()` is NOT
- * used because it hardcodes the SSR module graph, which doesn't contain
- * source maps for RSC modules (separate Vite environment with its own
- * module graph). This caused RSC errors to show transpiled line numbers
- * instead of original source positions.
+ * Stacks are shown as they arrive: Vite's module runner already reports
+ * source positions for the code it runs, and a second mapping pass moves
+ * them (TIM-1555).
  *
- * Design doc: 21-dev-server.md §"Error Overlay"
+ * Design doc: 21-dev-server.md §"Error Overlay", §"RSC Source-Mapping"
  */
 
-import type { ViteDevServer, DevEnvironment } from 'vite';
-import { createRequire } from 'node:module';
-import { resolve, dirname } from 'node:path';
-import { classifyFrame, type FrameType } from './stack-classifier.ts';
-
-// ─── Trace Mapping (lazy-loaded) ─────────────────────────────────────────────
-
-interface TraceMappingModule {
-  TraceMap: new (map: unknown) => unknown;
-  originalPositionFor: (
-    map: unknown,
-    needle: { line: number; column: number }
-  ) => { source: string | null; line: number | null; column: number | null };
-}
-
-let _traceMapping: TraceMappingModule | null = null;
-
-/**
- * Lazy-load @jridgewell/trace-mapping from Vite's dependency tree.
- * Vite bundles it internally; we resolve from Vite's package to avoid
- * adding a direct dependency.
- */
-function getTraceMapping(): TraceMappingModule {
-  if (_traceMapping) return _traceMapping;
-  // Resolve from Vite's package location so we pick up its transitive
-  // @jridgewell/trace-mapping without declaring it as a direct dependency.
-  // createRequire(import.meta.url) gives us ESM-compatible require (TIM-796),
-  // then we hop to Vite's path to reach its dependency tree (TIM-804).
-  const esmRequire = createRequire(import.meta.url);
-  const vitePath = esmRequire.resolve('vite');
-  const viteRequire = createRequire(vitePath);
-  _traceMapping = viteRequire('@jridgewell/trace-mapping') as TraceMappingModule;
-  return _traceMapping;
-}
+import type { ViteDevServer } from 'vite';
+import { classifyFrame } from './stack-classifier.ts';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -164,200 +128,13 @@ export function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhas
 import { formatTerminalError as _formatTerminalError } from './terminal.ts';
 export const formatTerminalError = _formatTerminalError;
 
-// ─── Module Runner Offset ───────────────────────────────────────────────────
-
-/**
- * Dynamically compute the line offset that Vite's module runner adds
- * when wrapping modules in an async function.
- *
- * Vite's `calculateOffsetOnce()` uses the same technique: create a new
- * AsyncFunction, throw from line 1, and check where the engine reports
- * the error. The difference between the reported line and 1 is the offset.
- *
- * This is engine-dependent (currently 2 on Node 18-22) and could change
- * in future Node.js or V8 versions. Computing it at runtime ensures we
- * always match the actual behavior.
- */
-let _cachedOffset: number | null = null;
-
-export function calculateModuleRunnerOffset(): number {
-  if (_cachedOffset !== null) return _cachedOffset;
-
-  try {
-    // Parse the AsyncFunction source to count wrapper lines before the body.
-    // AsyncFunction.toString() returns something like:
-    //   "async function anonymous(\n) {\nBODY\n}"
-    // The number of newlines before BODY is the offset Vite's module runner adds.
-    // eslint-disable-next-line no-new-func -- intentional: mirrors Vite's technique
-    const AsyncFunction = async function () {}.constructor as typeof Function;
-    const wrapper = new AsyncFunction('BODY');
-    const src = wrapper.toString();
-    const bodyIndex = src.indexOf('BODY');
-    if (bodyIndex === -1) {
-      _cachedOffset = 2; // fallback
-      return _cachedOffset;
-    }
-    const beforeBody = src.slice(0, bodyIndex);
-    const newlineCount = (beforeBody.match(/\n/g) || []).length;
-    _cachedOffset = newlineCount;
-  } catch (e) {
-    console.debug(
-      '[timber] overlay offset calculation failed:',
-      e instanceof Error ? e.message : e
-    );
-    _cachedOffset = 2; // fallback to known-good value
-  }
-
-  return _cachedOffset;
-}
-
-// ─── Stack Trace Source-Mapping ──────────────────────────────────────────────
-
-/**
- * Phases where the error originated in the RSC environment.
- * These use `server.environments.rsc.moduleGraph` for source-mapping.
- */
-const RSC_PHASES: ReadonlySet<ErrorPhase> = new Set(['render', 'access', 'middleware', 'handler']);
-
-/**
- * Rewrite an error's stack trace using the correct Vite environment module graph.
- *
- * `server.ssrFixStacktrace()` hardcodes `server.environments.ssr.moduleGraph`,
- * but RSC errors have stack frames pointing to modules loaded in the RSC
- * environment — a separate Vite module graph with separate transform results
- * and source maps. Using the SSR module graph silently fails to find the
- * modules, leaving transpiled/bundled line numbers in the stack trace.
- *
- * This function picks the RSC module graph for render-phase errors and falls
- * back to SSR for module-transform/proxy errors. If the first pass doesn't
- * rewrite any frames (e.g., mixed RSC+SSR stack), it tries the other graph.
- */
-function fixStacktraceForEnvironment(server: ViteDevServer, error: Error, phase: ErrorPhase): void {
-  if (!error.stack) return;
-
-  // Pick the primary environment based on error phase
-  const primaryEnvName = RSC_PHASES.has(phase) ? 'rsc' : 'ssr';
-  const fallbackEnvName = primaryEnvName === 'rsc' ? 'ssr' : 'rsc';
-
-  const primaryEnv = server.environments[primaryEnvName] as DevEnvironment | undefined;
-  const fallbackEnv = server.environments[fallbackEnvName] as DevEnvironment | undefined;
-
-  // Try primary environment first
-  if (primaryEnv?.moduleGraph) {
-    const rewritten = rewriteStacktrace(error.stack, primaryEnv.moduleGraph);
-    if (rewritten.changed) {
-      error.stack = rewritten.stack;
-      return;
-    }
-  }
-
-  // Fall back to the other environment if primary didn't rewrite anything
-  if (fallbackEnv?.moduleGraph) {
-    const rewritten = rewriteStacktrace(error.stack, fallbackEnv.moduleGraph);
-    if (rewritten.changed) {
-      error.stack = rewritten.stack;
-      return;
-    }
-  }
-}
-
-/**
- * Rewrite stack trace frames using source maps from an environment's module graph.
- *
- * Mirrors Vite's internal `ssrRewriteStacktrace` logic but works with any
- * `EnvironmentModuleGraph`, not just the SSR one.
- *
- * Returns the rewritten stack and whether any frames were actually changed.
- */
-function rewriteStacktrace(
-  stack: string,
-  moduleGraph: DevEnvironment['moduleGraph']
-): { stack: string; changed: boolean } {
-  let changed = false;
-
-  const result = stack
-    .split('\n')
-    .map((line) => {
-      return line.replace(
-        /^ {4}at (?:(\S.*?)\s\()?(.+?):(\d+)(?::(\d+))?\)?/,
-        (input, varName, id, lineStr, colStr) => {
-          if (!id) return input;
-
-          const mod = moduleGraph.getModuleById(id);
-          const rawSourceMap = mod?.transformResult?.map;
-          if (!rawSourceMap) return input;
-
-          // Vite's module runner wraps each module in an async function,
-          // adding N lines before the module body. The offset is computed
-          // dynamically to match the actual engine behavior (see TIM-783).
-          const OFFSET = calculateModuleRunnerOffset();
-          const origLine = Number(lineStr) - OFFSET;
-          const origCol = Number(colStr) - 1;
-          if (origLine <= 0 || origCol < 0) return input;
-
-          // Use @jridgewell/trace-mapping resolved from Vite's dependency tree.
-          // Vite bundles it internally; we resolve from Vite's package location
-          // to avoid adding a direct dependency.
-          let pos: { source: string | null; line: number | null; column: number | null };
-          try {
-            const { TraceMap: TM, originalPositionFor: opf } = getTraceMapping();
-            const traced = new TM(rawSourceMap);
-            pos = opf(traced, { line: origLine, column: origCol });
-          } catch (e) {
-            console.debug(
-              '[timber] source map tracing failed:',
-              e instanceof Error ? e.message : e
-            );
-            return input;
-          }
-
-          if (!pos.source || pos.line == null) return input;
-
-          changed = true;
-          const source = `${resolve(dirname(id), pos.source)}:${pos.line}:${(pos.column ?? 0) + 1}`;
-          const trimmedVarName = varName?.trim();
-          if (!trimmedVarName || trimmedVarName === 'eval') return `    at ${source}`;
-          return `    at ${trimmedVarName} (${source})`;
-        }
-      );
-    })
-    .join('\n');
-
-  return { stack: result, changed };
-}
-
-// ─── Error Source-Mapping (exported for use by fallback-error.ts) ────────────
-
-/**
- * Source-map an error's stack trace using the Vite dev server's module graph.
- *
- * Exported so that the fallback error renderer (fallback-error.ts) can
- * source-map errors before rendering the dev error page. Without this,
- * the dev error page shows transpiled positions (e.g. page.tsx:1:1 instead
- * of page.tsx:4:9).
- *
- * See TIM-811.
- */
-export function fixErrorStacktrace(server: ViteDevServer, error: Error, phase?: ErrorPhase): void {
-  fixStacktraceForEnvironment(
-    server,
-    error,
-    phase ?? classifyErrorPhase(error, server.config.root)
-  );
-}
-
 // ─── Overlay Integration ────────────────────────────────────────────────────
 
 /**
  * Send an error to Vite's browser overlay and log it to stderr.
  *
- * 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.
+ * Reads `error` and never writes it: the pipeline may render the same object
+ * on the fallback error page after reporting it here.
  *
  * The dev server remains running — errors are handled, not fatal.
  */
@@ -367,13 +144,6 @@ export function sendErrorToOverlay(
   phase: ErrorPhase,
   projectRoot: string
 ): void {
-  // Fix stack trace to use source-mapped positions.
-  // Use the RSC environment's module graph for render/access/middleware errors
-  // (which originate in the RSC environment), and fall back to SSR for others.
-  // server.ssrFixStacktrace() is NOT used — it hardcodes the SSR module graph
-  // which doesn't contain source maps for RSC-loaded modules.
-  fixStacktraceForEnvironment(server, error, phase);
-
   // Log to stderr with frame dimming
   const formatted = formatTerminalError(error, phase, projectRoot);
   process.stderr.write(`${formatted}\n`);