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

package/src/client/rsc-fetch.ts

@@ -18,11 +18,7 @@ import {
   RSC_KEY_PARAM,
 } from '../shared/rsc-cache-key.ts';
 import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.ts';
-import {
-  splitPayloadRoot,
-  readPublishedParams,
-  type PublishedParams,
-} from '../shared/payload-root.ts';
+import { splitPayloadRoot, type PublishedParams } from '../shared/payload-root.ts';
 import { normalizeBasePath, stripBasePath, withBasePath } from '../shared/base-path.ts';
 import { rscPayloadPath } from '../shared/rsc-payload-path.ts';
 import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
@@ -401,7 +397,8 @@ export class VersionSkewError extends Error {
 /**
  * Thrown when the server returns an error for an RSC payload request.
  * The server sends X-Timber-Error header and a JSON body instead of a
- * broken RSC stream for any RenderError (4xx or 5xx). Caught in
+ * RSC stream it cannot answer in-SPA (a deny that needs a fallback page, a
+ * broken first read). Caught in
  * navigate() to trigger a hard navigation so the server can render
  * the error page as HTML.
  *
@@ -487,9 +484,12 @@ function trackStreamCompletion(body: ReadableStream<Uint8Array>): {
 // ─── Fetch ───────────────────────────────────────────────────────
 
 /**
- * Fetch an RSC payload from the server. If a decodeRsc function is provided,
- * the response is decoded into a React element tree via createFromFetch.
- * Otherwise, the raw response text is returned (test mode).
+ * Fetch an RSC payload from the server and start decoding it.
+ *
+ * Every response is classified here, once: a version-skew reload, a 204 or
+ * 3xx redirect, a server error envelope and a non-RSC body are each turned
+ * into their error before `decodeRsc` sees the body. There is no second
+ * path — tests decode real Flight bytes through the same code (TIM-1541).
  */
 export async function fetchRscPayload(
   url: string,
@@ -518,156 +518,118 @@ export async function fetchRscPayload(
   // during that window would otherwise still hit the network with an
   // already-aborted signal.
   signal?.throwIfAborted();
-  if (deps.decodeRsc) {
-    // Production path: use createFromFetch for streaming RSC decoding.
-    // createFromFetch takes a Promise<Response> and progressively parses
-    // the RSC Flight stream as chunks arrive.
-    //
-    // Intercept the response to read segment metadata before createFromFetch
-    // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
-    let segmentInfo: SegmentInfo[] | null = null;
-    let skippedSegments: string[] | null = null;
-    // Track when the full RSC body stream is consumed (not just shell).
-    // Initialized to resolved for bodyless responses; overwritten when
-    // the response has a body.
-    let streamDone: Promise<void> = Promise.resolve();
-
-    const wrappedPromise = fetchPromise.then((response) => {
-      // Version skew detection (TIM-446): if the server signals a reload,
-      // throw VersionSkewError so the caller (router navigate) can trigger
-      // a full page reload.
-      if (checkReloadSignal(response)) {
-        throw new VersionSkewError();
-      }
-      // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
-      // for RSC payload requests instead of a raw 302, because fetch with
-      // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
-      // which crashes createFromFetch when it tries to read the body stream.
-      const redirectLocation =
-        response.headers.get('X-Timber-Redirect') ||
-        (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);
-      if (redirectLocation) {
-        throw new RedirectError(redirectLocation);
-      }
-      // Detect server error responses. The server returns X-Timber-Error header
-      // with a JSON body instead of a broken RSC stream for any RenderError
-      // (4xx or 5xx). Hard-navigate so the server renders the error page as HTML.
-      // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
-      if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
-        throw new ServerErrorResponse(response.status, url);
-      }
-      // Content-Type guard: reject non-RSC responses before createFromFetch
-      // tries to parse the body as Flight data.
-      // In static mode, accept octet-stream/text/plain/absent content-type
-      // (static hosts serve .rsc files with these), but still reject 404s
-      // and text/html (missing .rsc file → host returns 404 page or SPA
-      // HTML fallback). See TIM-1231, TIM-1243, TIM-1247.
-      if (staticMode) {
-        const contentType = response.headers.get('content-type');
-        if (
-          !response.ok ||
-          (contentType && contentType.split(';')[0].trim().toLowerCase() === 'text/html')
-        ) {
-          response.body?.cancel();
-          throw new NonRscResponse(url);
-        }
-      } else {
-        if (!isRscContentType(response.headers.get('content-type'))) {
-          response.body?.cancel();
-          throw new NonRscResponse(url);
-        }
+  // createFromFetch takes a Promise<Response> and progressively parses
+  // the RSC Flight stream as chunks arrive.
+  //
+  // Intercept the response to read segment metadata before createFromFetch
+  // consumes the body. Reading headers does NOT consume the body stream.
+  const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
+  let segmentInfo: SegmentInfo[] | null = null;
+  let skippedSegments: string[] | null = null;
+  // Track when the full RSC body stream is consumed (not just shell).
+  // Initialized to resolved for bodyless responses; overwritten when
+  // the response has a body.
+  let streamDone: Promise<void> = Promise.resolve();
+
+  const wrappedPromise = fetchPromise.then((response) => {
+    // Version skew detection (TIM-446): if the server signals a reload,
+    // throw VersionSkewError so the caller (router navigate) can trigger
+    // a full page reload.
+    if (checkReloadSignal(response)) {
+      throw new VersionSkewError();
+    }
+    // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
+    // for RSC payload requests instead of a raw 302, because fetch with
+    // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
+    // which crashes createFromFetch when it tries to read the body stream.
+    const redirectLocation =
+      response.headers.get('X-Timber-Redirect') ||
+      (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);
+    if (redirectLocation) {
+      throw new RedirectError(redirectLocation);
+    }
+    // Detect server error responses. The server returns X-Timber-Error header
+    // with a JSON body instead of an RSC stream it cannot answer in-SPA.
+    // Hard-navigate so the server renders the error page as HTML.
+    // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+    if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
+      throw new ServerErrorResponse(response.status, url);
+    }
+    // Content-Type guard: reject non-RSC responses before createFromFetch
+    // tries to parse the body as Flight data.
+    // In static mode, accept octet-stream/text/plain/absent content-type
+    // (static hosts serve .rsc files with these), but still reject 404s
+    // and text/html (missing .rsc file → host returns 404 page or SPA
+    // HTML fallback). See TIM-1231, TIM-1243, TIM-1247.
+    if (staticMode) {
+      const contentType = response.headers.get('content-type');
+      if (
+        !response.ok ||
+        (contentType && contentType.split(';')[0].trim().toLowerCase() === 'text/html')
+      ) {
+        response.body?.cancel();
+        throw new NonRscResponse(url);
       }
-      // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
-      // as React elements — React 19 Float handles them. See TIM-1151.
-      segmentInfo = extractSegmentInfo(response);
-      skippedSegments = extractSkippedSegments(response);
-
-      // Wrap the body to track full stream consumption. createFromFetch's
-      // thenable resolves when the root model (shell) arrives, but we need
-      // to know when ALL chunks are read — that is what the navigation
-      // promise resolving means, and what keeps the pending store set.
-      if (response.body) {
-        const tracked = trackStreamCompletion(response.body);
-        streamDone = tracked.done;
-        streamDone.catch(() => {}); // prevent unhandled rejection
-        return new Response(tracked.body, {
-          headers: response.headers,
-          status: response.status,
-        });
+    } else {
+      if (!isRscContentType(response.headers.get('content-type'))) {
+        response.body?.cancel();
+        throw new NonRscResponse(url);
       }
-      return response;
-    });
-    // Await headers so segmentInfo is populated.
-    await wrappedPromise;
-    // Start decoding but do NOT await — return the in-progress thenable.
-    // React can render a Flight thenable directly: it suspends on unresolved
-    // parts and progressively renders as chunks arrive, spreading work across
-    // frames instead of blocking the main thread in one burst.
-    const root = deps.decodeRsc(wrappedPromise);
-    // One split, one root: the tree and the params it was rendered with come
-    // apart here and nowhere else, so nothing downstream has to keep them
-    // paired by hand.
-    const { tree: payload, params } = splitPayloadRoot(root);
-    // Combine stream completion with payload error propagation.
-    // streamDone marks the end of the RSC stream, which is what the
-    // navigation promise resolves on. payloadError propagates
-    // decode failures (stale client references, Flight parse errors)
-    // so the router's catch block can trigger recovery (stale reload).
-    const payloadError = new Promise<void>((_, reject) => {
-      Promise.resolve(root).then(() => {}, reject);
-    });
-    payloadError.catch(() => {});
-    const decodePromise = Promise.race([streamDone, payloadError]);
-    // Mark handled, like payloadError above. The same rejection reaches the
-    // router through `payload`, and a navigation that recovers by hard
-    // navigating (version skew, non-RSC response) hangs deliberately and never
-    // awaits this one — leaving it to surface as an unhandled rejection.
-    decodePromise.catch(() => {});
-    return {
-      payload,
-      params,
-      decodePromise,
-      segmentInfo,
-      skippedSegments,
-    };
-  }
-  // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
-  // Check for redirect in test path too
-  if (response.status >= 300 && response.status < 400) {
-    const location = response.headers.get('Location');
-    if (location) {
-      throw new RedirectError(location);
-    }
-  }
-  // Server error guard (same as production path above).
-  if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
-    throw new ServerErrorResponse(response.status, url);
-  }
-  // Content-Type guard (same as production path above). See TIM-1231, TIM-1243, TIM-1247.
-  if (staticMode) {
-    const fallbackContentType = response.headers.get('content-type');
-    if (
-      !response.ok ||
-      (fallbackContentType &&
-        fallbackContentType.split(';')[0].trim().toLowerCase() === 'text/html')
-    ) {
-      response.body?.cancel();
-      throw new NonRscResponse(url);
     }
-  } else {
-    if (!isRscContentType(response.headers.get('content-type'))) {
-      response.body?.cancel();
-      throw new NonRscResponse(url);
+    // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
+    // as React elements — React 19 Float handles them. See TIM-1151.
+    segmentInfo = extractSegmentInfo(response);
+    skippedSegments = extractSkippedSegments(response);
+
+    // Wrap the body to track full stream consumption. createFromFetch's
+    // thenable resolves when the root model (shell) arrives, but we need
+    // to know when ALL chunks are read — that is what the navigation
+    // promise resolving means, and what keeps the pending store set.
+    if (response.body) {
+      const tracked = trackStreamCompletion(response.body);
+      streamDone = tracked.done;
+      streamDone.catch(() => {}); // prevent unhandled rejection
+      return new Response(tracked.body, {
+        headers: response.headers,
+        status: response.status,
+      });
     }
-  }
-  // Test/fallback path: raw text carries no payload root, so no params.
+    return response;
+  });
+  // Await headers so segmentInfo is populated.
+  await wrappedPromise;
+  // Start decoding but do NOT await — return the in-progress thenable.
+  // React can render a Flight thenable directly: it suspends on unresolved
+  // parts and progressively renders as chunks arrive, spreading work across
+  // frames instead of blocking the main thread in one burst.
+  const root = deps.decodeRsc(wrappedPromise);
+  // One split, one root: the tree and the params it was rendered with come
+  // apart here and nowhere else, so nothing downstream has to keep them
+  // paired by hand.
+  const { tree: payload, params } = splitPayloadRoot(root);
+  // Settles once the stream has ended AND the root has decoded, and rejects
+  // as soon as either fails. streamDone marks the end of the RSC stream,
+  // which is what the navigation promise resolves on; the root's rejection
+  // carries decode failures (stale client references, Flight parse errors)
+  // so the router's catch block can trigger recovery (stale reload).
+  //
+  // Not a race between the two: a payload that arrives whole — a small
+  // static `.rsc` file — ends its stream before Flight rejects the root it
+  // could not decode, and a race resolved on the stream, so the failure
+  // never reached recovery and the skew was never recorded (TIM-1541).
+  const rootDecoded = Promise.resolve(root).then(() => {});
+  rootDecoded.catch(() => {});
+  const decodePromise = Promise.all([streamDone, rootDecoded]).then(() => {});
+  // Mark handled, like rootDecoded above. The same rejection reaches the
+  // router through `payload`, and a navigation that recovers by hard
+  // navigating (version skew, non-RSC response) hangs deliberately and never
+  // awaits this one — leaving it to surface as an unhandled rejection.
+  decodePromise.catch(() => {});
   return {
-    payload: await response.text(),
-    params: readPublishedParams(undefined),
-    decodePromise: null,
-    segmentInfo: extractSegmentInfo(response),
-    skippedSegments: extractSkippedSegments(response),
+    payload,
+    params,
+    decodePromise,
+    segmentInfo,
+    skippedSegments,
   };
 }

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();
+}