@timber-js/app 0.2.0-alpha.197 → 0.2.0-alpha.199

package/dist/_chunks/{logger-DDirEsn7.js → logger-uLBuGKDI.js}

@@ -4,214 +4,27 @@ import { a as assertValidCookieOptions, i as assertValidCookieName, n as parseSe
 import { r as appVisibleSearch } from "./rsc-cache-key-ClUiXQnK.js";
 import { a as mergePreservedSearchParams, o as resolveSegmentParams, r as validateExternalRedirectUrl, t as assertRelativeRedirectPath } from "./href-validation-BIrxavIy.js";
 import { randomUUID } from "node:crypto";
-//#region src/server/tracing.ts
-/**
-* Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
-*
-* getTraceId() is always available in server code (middleware, access, components, actions).
-* Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
-* or a crypto.randomUUID()-derived fallback otherwise.
-*
-* See design/17-logging.md §"trace_id is Always Set"
-*/
-/**
-* Returns the current request's trace ID — always a 32-char lowercase hex string.
-*
-* With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).
-* Without OTEL: crypto.randomUUID() with hyphens stripped.
-*
-* Throws if called outside a request context (no ALS store).
-*/
-function getTraceId() {
-	const store = traceAls.getStore();
-	if (!store) throw new Error("[timber] getTraceId() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
-	return store.traceId;
-}
-/**
-* Returns the current OTEL span ID if available, undefined otherwise.
-*/
-function getSpanId() {
-	return traceAls.getStore()?.spanId;
-}
-/**
-* Generate a 32-char lowercase hex ID from crypto.randomUUID().
-* Same format as OTEL trace IDs — zero-friction upgrade path.
-*/
-function generateTraceId() {
-	return randomUUID().replace(/-/g, "");
-}
-/**
-* Run a callback within a trace context. Used by the pipeline to establish
-* per-request ALS scope.
-*/
-function runWithTraceId(id, fn) {
-	return traceAls.run({ traceId: id }, fn);
-}
-/**
-* Replace the trace ID in the current ALS store. Used when OTEL creates
-* a root span and we want to switch from the UUID fallback to the real
-* OTEL trace ID.
-*/
-function replaceTraceId(newTraceId, newSpanId) {
-	const store = traceAls.getStore();
-	if (store) {
-		store.traceId = newTraceId;
-		store.spanId = newSpanId;
-	}
-}
-/**
-* Update the span ID in the current ALS store. Used when entering a new
-* OTEL span to keep log–trace correlation accurate.
-*/
-function updateSpanId(newSpanId) {
-	const store = traceAls.getStore();
-	if (store) store.spanId = newSpanId;
-}
-/**
-* Get the current trace store, or undefined if outside a request context.
-* Framework-internal — use getTraceId()/getSpanId() in user code.
-*/
-function getTraceStore() {
-	return traceAls.getStore();
-}
-var PLATFORM_TRACER_KEY = Symbol.for("timber:platform-tracer");
-/** The registered native platform tracer, if any. */
-function getPlatformTracer() {
-	return globalThis[PLATFORM_TRACER_KEY];
-}
-/**
-* Attempt to get the @opentelemetry/api tracer. Returns undefined if the
-* package is not installed or no SDK is registered.
-*
-* timber.js depends on @opentelemetry/api as the vendor-neutral interface.
-* The API is a no-op by default — spans are only emitted when the developer
-* initializes an SDK in register().
-*/
-var _otelApi;
-async function getOtelApi() {
-	if (_otelApi === void 0) try {
-		_otelApi = await import("@opentelemetry/api");
-	} catch {
-		_otelApi = null;
-	}
-	return _otelApi;
-}
-/** OTEL tracer instance, lazily created. */
-var _tracer;
-/**
-* Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.
-*/
-async function getTracer() {
-	if (_tracer === void 0) {
-		const api = await getOtelApi();
-		if (api) _tracer = api.trace.getTracer("timber.js");
-		else _tracer = null;
-	}
-	return _tracer;
-}
+//#region src/server/waituntil-bridge.ts
 /**
-* Run a function within a framework span. Composes two emission channels:
+* Per-request waitUntil bridge — ALS bridge for platform adapters.
 *
-* - **Native platform span** — when an adapter registered a PlatformTracer
-*   (Cloudflare Workers), the fn is wrapped in platformTracer.enterSpan()
-*   so it appears in the platform's native trace view.
-* - **OTEL span** — when an OTEL SDK is active, the fn also runs inside an
-*   OTEL span (dual emission). No SDK and no platform tracer = zero overhead.
+* The generated entry point (Nitro, Cloudflare) wraps the handler with
+* `runWithWaitUntil`, binding the platform's lifecycle extension function
+* (e.g., h3's `event.waitUntil()` or CF's `ctx.waitUntil()`) for the
+* request duration. The `waitUntil()` primitive reads from this ALS to
+* dispatch background work to the correct platform API.
 *
-* Automatically:
-* - Creates the span as a child of the current context
-* - Updates the ALS span ID for log–trace correlation
-* - Ends the span when the function completes
-* - Records exceptions on error (OTEL channel)
-*/
-async function withSpan(name, attributes, fn) {
-	const platformTracer = getPlatformTracer();
-	if (!platformTracer) return runOtelSpan(name, attributes, fn);
-	return platformTracer.enterSpan(name, async (span) => {
-		for (const key of Object.keys(attributes)) span.setAttribute(key, attributes[key]);
-		const store = traceAls.getStore();
-		const prevPlatformSpan = store?.platformSpan;
-		if (store) store.platformSpan = span;
-		try {
-			return await runOtelSpan(name, attributes, fn);
-		} finally {
-			if (store) store.platformSpan = prevPlatformSpan;
-		}
-	});
-}
-/** The OTEL half of withSpan() — no-op passthrough when no SDK is active. */
-async function runOtelSpan(name, attributes, fn) {
-	const tracer = await getTracer();
-	if (!tracer) return fn();
-	const api = await getOtelApi();
-	return tracer.startActiveSpan(name, { attributes }, async (span) => {
-		const prevSpanId = getSpanId();
-		updateSpanId(span.spanContext().spanId);
-		try {
-			const result = await fn();
-			span.setStatus({ code: api.SpanStatusCode.OK });
-			return result;
-		} catch (error) {
-			span.setStatus({ code: api.SpanStatusCode.ERROR });
-			if (error instanceof Error) span.recordException(error);
-			throw error;
-		} finally {
-			span.end();
-			updateSpanId(prevSpanId);
-		}
-	});
-}
-/**
-* Set an attribute on the current active span (if any).
-* Used for setting span attributes after span creation (e.g. timber.result on access spans).
-*/
-async function setSpanAttribute(key, value) {
-	const platformSpan = traceAls.getStore()?.platformSpan;
-	if (platformSpan) platformSpan.setAttribute(key, value);
-	const api = await getOtelApi();
-	if (!api) return;
-	const activeSpan = api.trace.getActiveSpan();
-	if (activeSpan) activeSpan.setAttribute(key, value);
-}
-/**
-* Add a span event to the current active span (if any).
-* Used for timber.cache HIT/MISS events — recorded as span events, not child spans.
+* Design doc: design/11-platform.md §"waitUntil()"
 */
-async function addSpanEvent(name, attributes) {
-	const api = await getOtelApi();
-	if (!api) return;
-	const activeSpan = api.trace.getActiveSpan();
-	if (activeSpan) activeSpan.addEvent(name, attributes);
-}
 /**
-* Fire-and-forget span event — no await, no microtask overhead.
-*
-* Used on the cache hot path where awaiting addSpanEvent creates an
-* unnecessary microtask per cache operation. If OTEL is not loaded yet,
-* the event is silently dropped (acceptable for diagnostics).
+* Get the current request's waitUntil function, if available.
 *
-* See TIM-370 for perf motivation.
-*/
-function addSpanEventSync(name, attributes) {
-	if (!_otelApi) return;
-	const activeSpan = _otelApi.trace.getActiveSpan();
-	if (activeSpan) activeSpan.addEvent(name, attributes);
-}
-/**
-* Try to extract the OTEL trace ID from the current active span context.
-* Returns undefined if OTEL is not active or no span exists.
+* Returns undefined when no platform adapter has installed a waitUntil
+* handler for the current request (e.g., on platforms that don't support
+* lifecycle extension, or outside a request context).
 */
-async function getOtelTraceId() {
-	const api = await getOtelApi();
-	if (!api) return void 0;
-	const activeSpan = api.trace.getActiveSpan();
-	if (!activeSpan) return void 0;
-	const ctx = activeSpan.spanContext();
-	if (!ctx.traceId || ctx.traceId === "00000000000000000000000000000000") return;
-	return {
-		traceId: ctx.traceId,
-		spanId: ctx.spanId
-	};
+function getWaitUntil() {
+	return waitUntilAls.getStore();
 }
 //#endregion
 //#region src/server/debug.ts
@@ -319,237 +132,32 @@ function _readTimberDebugEnv() {
 	return false;
 }
 //#endregion
-//#region src/server/error-formatter.ts
+//#region src/server/cookie-parsing.ts
 /**
-* Error Formatter — rewrites SSR/RSC error messages to surface user code.
+* Cookie parsing and serialization helpers — pure string ↔ structure
+* functions with no ALS dependency. Split out of `cookie-context.ts`
+* (TIM-853) so the API surface and the wire-format codecs can each be
+* read on their own.
 *
-* When React or Vite throw errors during SSR, stack traces reference
-* vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
-* and mangled export names (`__vite_ssr_export_default__`). This module
-* rewrites error messages and stack traces to point at user code instead.
+* The functions in this module are total over arbitrary input. They
+* never throw and never call `assertValid*` (the security validators
+* live in the API surface — `cookie-context.ts` invokes them at every
+* jar entry point so the smuggling-primitive invariant from TIM-868
+* is enforced regardless of which path produced the bytes).
 *
-* Dev-only — in production, errors go through the structured logger
-* without formatting.
+* Delegates to the `cookie` package (RFC 6265, dependency-free,
+* browser-safe) for wire codecs. Adapts at the boundary to preserve
+* timber's Map-based API and never-throw contract.
 */
 /**
-* Patterns that identify internal Vite/RSC vendor paths in stack traces.
-* These are replaced with human-readable labels.
-*/
-var VENDOR_PATH_PATTERNS = [
-	{
-		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor_react-server-dom[^\s)]+/g,
-		replacement: "<react-server-dom>"
-	},
-	{
-		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor[^\s)]+/g,
-		replacement: "<rsc-vendor>"
-	},
-	{
-		pattern: /node_modules\/\.vite\/deps_ssr\/[^\s)]+/g,
-		replacement: "<vite-dep>"
-	},
-	{
-		pattern: /node_modules\/\.vite\/deps\/[^\s)]+/g,
-		replacement: "<vite-dep>"
-	}
-];
-/**
-* Patterns that identify Vite-mangled export names in error messages.
-*/
-var MANGLED_NAME_PATTERNS = [{
-	pattern: /__vite_ssr_export_default__/g,
-	replacement: "<default export>"
-}, {
-	pattern: /__vite_ssr_export_(\w+)__/g,
-	replacement: "<export $1>"
-}];
-/**
-* Rewrite an error's message and stack to replace internal Vite paths
-* and mangled names with human-readable labels.
-*/
-function formatSsrError(error) {
-	if (!(error instanceof Error)) return String(error);
-	let message = error.message;
-	let stack = error.stack ?? "";
-	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) message = message.replace(pattern, replacement);
-	for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) stack = stack.replace(pattern, replacement);
-	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) stack = stack.replace(pattern, replacement);
-	const hint = extractErrorHint(error.message);
-	const parts = [];
-	parts.push(message);
-	if (hint) parts.push(`  → ${hint}`);
-	const userFrames = extractUserFrames(stack);
-	if (userFrames.length > 0) {
-		parts.push("");
-		parts.push("  User code in stack:");
-		for (const frame of userFrames) parts.push(`    ${frame}`);
-	}
-	return parts.join("\n");
-}
-/**
-* Extract a human-readable hint from common React/RSC error messages.
-*
-* React error messages contain useful information but the surrounding
-* context (vendor paths, mangled names) obscures it. This extracts the
-* actionable part as a one-line hint.
-*/
-function extractErrorHint(message) {
-	if (message.match(/Functions cannot be passed directly to Client Components/)) {
-		const propMatch = message.match(/<[^>]*?\s(\w+)=\{function/);
-		if (propMatch) return `Prop "${propMatch[1]}" is a function — mark it "use server" or call it before passing`;
-		return "A function prop was passed to a Client Component — mark it \"use server\" or call it before passing";
-	}
-	if (message.includes("Objects are not valid as a React child")) return "An object was rendered as JSX children — convert to string or extract the value";
-	const nullRefMatch = message.match(/Cannot read propert(?:y|ies) of (undefined|null) \(reading '(\w+)'\)/);
-	if (nullRefMatch) return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;
-	const notFnMatch = message.match(/(\w+) is not a function/);
-	if (notFnMatch) return `"${notFnMatch[1]}" is not a function — check imports and exports`;
-	if (message.includes("Element type is invalid")) return "A component resolved to undefined/null — check default exports and import paths";
-	if (message.includes("Invalid hook call")) return "A hook was called outside of a React component render. If this is a 'use client' component, ensure the directive is at the very top of the file (before any imports) and that @vitejs/plugin-rsc is loaded correctly. Barrel re-exports from non-'use client' files do not propagate the directive.";
-	return null;
-}
-/**
-* Extract stack frames that reference user code (not node_modules,
-* not framework internals).
-*
-* Returns at most 5 frames to keep output concise.
-*/
-function extractUserFrames(stack) {
-	const lines = stack.split("\n");
-	const userFrames = [];
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (!trimmed.startsWith("at ")) continue;
-		if (trimmed.includes("node_modules") || trimmed.includes("<react-server-dom>") || trimmed.includes("<rsc-vendor>") || trimmed.includes("<vite-dep>") || trimmed.includes("node:internal")) continue;
-		userFrames.push(trimmed);
-		if (userFrames.length >= 5) break;
-	}
-	return userFrames;
-}
-//#endregion
-//#region src/server/default-logger.ts
-/**
-* DefaultLogger — human-readable stderr logging when no custom logger is configured.
-*
-* Ships as the fallback so production deployments always have error visibility,
-* even without an `instrumentation.ts` logger export. Output is one line per
-* event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
-*
-* Format:
-*   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
-*   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
-*   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
-*
-* Behavior:
-* - Suppressed entirely in dev mode (dev logging handles all output)
-* - `debug` suppressed unless TIMBER_DEBUG is set
-* - Replaced entirely when a custom logger is set via `setLogger()`
-*
-* See design/17-logging.md §"DefaultLogger"
-*/
-/**
-* Format data fields as `key=value` pairs for human-readable output.
-* - `error` key is serialized via formatSsrError for stack trace cleanup
-* - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
-* - Other values are stringified inline
-*/
-function formatDataFields(data) {
-	if (!data) return "";
-	const parts = [];
-	let traceId;
-	for (const [key, value] of Object.entries(data)) {
-		if (key === "trace_id") {
-			traceId = typeof value === "string" ? value : String(value);
-			continue;
-		}
-		if (key === "error") {
-			parts.push(`error=${formatSsrError(value)}`);
-			continue;
-		}
-		if (value === void 0 || value === null) continue;
-		parts.push(`${key}=${value}`);
-	}
-	if (traceId) parts.push(`trace_id=${traceId.slice(0, 8)}`);
-	return parts.length > 0 ? "  " + parts.join("  ") : "";
-}
-/** Pad level string to fixed width for alignment. */
-function padLevel(level) {
-	return level.padEnd(5);
-}
-function createDefaultLogger() {
-	return {
-		error(msg, data) {
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("ERROR")}  ${msg}${fields}\n`);
-		},
-		warn(msg, data) {
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("WARN")}  ${msg}${fields}\n`);
-		},
-		info(msg, data) {
-			if (isDevMode()) return;
-			if (!isDebug()) return;
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("INFO")}  ${msg}${fields}\n`);
-		},
-		debug(msg, data) {
-			if (isDevMode()) return;
-			if (!isDebug()) return;
-			const fields = formatDataFields(data);
-			process.stderr.write(`[timber] ${padLevel("DEBUG")}  ${msg}${fields}\n`);
-		}
-	};
-}
-//#endregion
-//#region src/server/waituntil-bridge.ts
-/**
-* Per-request waitUntil bridge — ALS bridge for platform adapters.
-*
-* The generated entry point (Nitro, Cloudflare) wraps the handler with
-* `runWithWaitUntil`, binding the platform's lifecycle extension function
-* (e.g., h3's `event.waitUntil()` or CF's `ctx.waitUntil()`) for the
-* request duration. The `waitUntil()` primitive reads from this ALS to
-* dispatch background work to the correct platform API.
-*
-* Design doc: design/11-platform.md §"waitUntil()"
-*/
-/**
-* Get the current request's waitUntil function, if available.
-*
-* Returns undefined when no platform adapter has installed a waitUntil
-* handler for the current request (e.g., on platforms that don't support
-* lifecycle extension, or outside a request context).
-*/
-function getWaitUntil() {
-	return waitUntilAls.getStore();
-}
-//#endregion
-//#region src/server/cookie-parsing.ts
-/**
-* Cookie parsing and serialization helpers — pure string ↔ structure
-* functions with no ALS dependency. Split out of `cookie-context.ts`
-* (TIM-853) so the API surface and the wire-format codecs can each be
-* read on their own.
-*
-* The functions in this module are total over arbitrary input. They
-* never throw and never call `assertValid*` (the security validators
-* live in the API surface — `cookie-context.ts` invokes them at every
-* jar entry point so the smuggling-primitive invariant from TIM-868
-* is enforced regardless of which path produced the bytes).
-*
-* Delegates to the `cookie` package (RFC 6265, dependency-free,
-* browser-safe) for wire codecs. Adapts at the boundary to preserve
-* timber's Map-based API and never-throw contract.
-*/
-/**
-* Parse a Cookie header string into a Map of name → value pairs.
-* Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.
-*
-* Values are auto-decoded with `decodeURIComponent` so they round-trip
-* losslessly with `getCookies().set()` (which auto-encodes). Malformed
-* `%`-escapes from third-party cookies fall back to the raw byte sequence
-* — the parser must be total over arbitrary inbound headers, including
-* non-conforming values from other servers, browser extensions, etc.
+* Parse a Cookie header string into a Map of name → value pairs.
+* Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.
+*
+* Values are auto-decoded with `decodeURIComponent` so they round-trip
+* losslessly with `getCookies().set()` (which auto-encodes). Malformed
+* `%`-escapes from third-party cookies fall back to the raw byte sequence
+* — the parser must be total over arbitrary inbound headers, including
+* non-conforming values from other servers, browser extensions, etc.
 */
 function parseCookieHeader(header) {
 	const map = /* @__PURE__ */ new Map();
@@ -1110,28 +718,53 @@ function warnIfNotSerializable(data, callerName) {
 	const issue = findNonSerializable(data);
 	if (issue) console.warn(`[timber] ${callerName}: ${issue}. Data passed to deny() or RenderError must be JSON-serializable because the post-flush path uses JSON.stringify, not React Flight.`);
 }
+var DENY_BRAND = Symbol.for("timber:signal.deny");
+var REDIRECT_BRAND = Symbol.for("timber:signal.redirect");
+var RENDER_ERROR_BRAND = Symbol.for("timber:signal.render-error");
+var SSR_STREAM_ERROR_BRAND = Symbol.for("timber:signal.ssr-stream-error");
+function hasBrand(value, brand) {
+	return typeof value === "object" && value !== null && brand in value;
+}
+/** True for any `DenySignal`, regardless of which module evaluation created it. */
+function isDenySignal(error) {
+	return hasBrand(error, DENY_BRAND);
+}
+/** True for any `RedirectSignal`, regardless of which module evaluation created it. */
+function isRedirectSignal(error) {
+	return hasBrand(error, REDIRECT_BRAND);
+}
+/**
+* True for any `SsrStreamError`. This one also crosses Vite environments:
+* it is thrown in SSR and caught in RSC, which are separate module graphs in
+* the same process — the brand is the only identity the two share.
+*/
+function isSsrStreamError(error) {
+	return hasBrand(error, SSR_STREAM_ERROR_BRAND);
+}
 /**
 * Render-phase signal thrown by `deny()`. Caught by the framework to produce
 * the correct HTTP status code (segment context) or graceful degradation (slot context).
+*
+* Detect with `isDenySignal()`, never `instanceof` — see "Signal branding" above.
 */
 var DenySignal = class extends Error {
+	[DENY_BRAND] = true;
 	status;
 	data;
 	/**
-	* Segment key of the segment that owns the deny page matched for this
-	* signal — set by a framework catch site that matched an entry it may not
-	* render at its own position, and re-threw so the boundary at the owning
-	* segment renders it instead.
+	* Ordered list of segment keys that own matching deny pages for this
+	* signal, best match first. Present = addressed (a boundary should
+	* render it); absent = unplaced (the re-render fallback serves it).
 	*
-	* Written only by the three in-tree catch sites (`PageDenyBoundary`,
-	* `TracedLayout`, `AccessGate`), never by user code. Two readers depend on
-	* it: `TimberErrorBoundary`, which declines any deny whose `ownerKey` is
-	* not its own `segmentKey`, and `buildRscPayloadResponse`, which keeps
-	* streaming instead of re-rendering when it is set.
+	* In-tree hoists stamp a single-element list (`[entry.ownerKey]`) —
+	* identical to the pre-TIM-1450 `ownerKey`. Late addressing (TIM-1450)
+	* stamps the full candidate list so the client can find the first
+	* *reachable* owner via its ancestry context, eliminating the
+	* owner-below-throw-site escape.
 	*
 	* See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
 	*/
-	ownerKey;
+	owners;
 	/**
 	* When true, the pipeline must respond with `rscErrorEnvelope` so the
 	* client hard-navigates instead of attempting to render a deny page
@@ -1207,8 +840,11 @@ function deny(statusOrOptions, data) {
 /**
 * Render-phase signal thrown by `redirect()` and `redirectExternal()`.
 * Caught by the framework to produce a 3xx response or client-side navigation.
+*
+* Detect with `isRedirectSignal()`, never `instanceof` — see "Signal branding" above.
 */
 var RedirectSignal = class extends Error {
+	[REDIRECT_BRAND] = true;
 	location;
 	status;
 	constructor(location, status) {
@@ -1226,7 +862,7 @@ var RedirectSignal = class extends Error {
 * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
 */
 function isControlFlowSignal(error) {
-	if (error instanceof DenySignal || error instanceof RedirectSignal) return true;
+	if (isDenySignal(error) || isRedirectSignal(error)) return true;
 	if (error && typeof error === "object") {
 		const digest = error.digest;
 		if (typeof digest === "string") try {
@@ -1297,8 +933,11 @@ function redirectExternal(url, allowList, status = 302) {
 *   resourceId: params.id,
 * })
 * ```
+*
+* Detect with `isRenderError()`, never `instanceof` — see "Signal branding" above.
 */
 var RenderError = class extends Error {
+	[RENDER_ERROR_BRAND] = true;
 	code;
 	digest;
 	status;
@@ -1340,6 +979,398 @@ function waitUntil(promise) {
 	}
 }
 //#endregion
+//#region src/server/tracing.ts
+/**
+* Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
+*
+* getTraceId() is always available in server code (middleware, access, components, actions).
+* Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
+* or a crypto.randomUUID()-derived fallback otherwise.
+*
+* See design/17-logging.md §"trace_id is Always Set"
+*/
+/**
+* Returns the current request's trace ID — always a 32-char lowercase hex string.
+*
+* With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).
+* Without OTEL: crypto.randomUUID() with hyphens stripped.
+*
+* Throws if called outside a request context (no ALS store).
+*/
+function getTraceId() {
+	const store = traceAls.getStore();
+	if (!store) throw new Error("[timber] getTraceId() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
+	return store.traceId;
+}
+/**
+* Returns the current OTEL span ID if available, undefined otherwise.
+*/
+function getSpanId() {
+	return traceAls.getStore()?.spanId;
+}
+/**
+* Generate a 32-char lowercase hex ID from crypto.randomUUID().
+* Same format as OTEL trace IDs — zero-friction upgrade path.
+*/
+function generateTraceId() {
+	return randomUUID().replace(/-/g, "");
+}
+/**
+* Run a callback within a trace context. Used by the pipeline to establish
+* per-request ALS scope.
+*/
+function runWithTraceId(id, fn) {
+	return traceAls.run({ traceId: id }, fn);
+}
+/**
+* Replace the trace ID in the current ALS store. Used when OTEL creates
+* a root span and we want to switch from the UUID fallback to the real
+* OTEL trace ID.
+*/
+function replaceTraceId(newTraceId, newSpanId) {
+	const store = traceAls.getStore();
+	if (store) {
+		store.traceId = newTraceId;
+		store.spanId = newSpanId;
+	}
+}
+/**
+* Update the span ID in the current ALS store. Used when entering a new
+* OTEL span to keep log–trace correlation accurate.
+*/
+function updateSpanId(newSpanId) {
+	const store = traceAls.getStore();
+	if (store) store.spanId = newSpanId;
+}
+/**
+* Get the current trace store, or undefined if outside a request context.
+* Framework-internal — use getTraceId()/getSpanId() in user code.
+*/
+function getTraceStore() {
+	return traceAls.getStore();
+}
+var PLATFORM_TRACER_KEY = Symbol.for("timber:platform-tracer");
+/** The registered native platform tracer, if any. */
+function getPlatformTracer() {
+	return globalThis[PLATFORM_TRACER_KEY];
+}
+/**
+* Attempt to get the @opentelemetry/api tracer. Returns undefined if the
+* package is not installed or no SDK is registered.
+*
+* timber.js depends on @opentelemetry/api as the vendor-neutral interface.
+* The API is a no-op by default — spans are only emitted when the developer
+* initializes an SDK in register().
+*/
+var _otelApi;
+async function getOtelApi() {
+	if (_otelApi === void 0) try {
+		_otelApi = await import("@opentelemetry/api");
+	} catch {
+		_otelApi = null;
+	}
+	return _otelApi;
+}
+/** OTEL tracer instance, lazily created. */
+var _tracer;
+/**
+* Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.
+*/
+async function getTracer() {
+	if (_tracer === void 0) {
+		const api = await getOtelApi();
+		if (api) _tracer = api.trace.getTracer("timber.js");
+		else _tracer = null;
+	}
+	return _tracer;
+}
+/**
+* Run a function within a framework span. Composes two emission channels:
+*
+* - **Native platform span** — when an adapter registered a PlatformTracer
+*   (Cloudflare Workers), the fn is wrapped in platformTracer.enterSpan()
+*   so it appears in the platform's native trace view.
+* - **OTEL span** — when an OTEL SDK is active, the fn also runs inside an
+*   OTEL span (dual emission). No SDK and no platform tracer = zero overhead.
+*
+* Automatically:
+* - Creates the span as a child of the current context
+* - Updates the ALS span ID for log–trace correlation
+* - Ends the span when the function completes
+* - Records exceptions on error (OTEL channel)
+*/
+async function withSpan(name, attributes, fn) {
+	const platformTracer = getPlatformTracer();
+	if (!platformTracer) return runOtelSpan(name, attributes, fn);
+	return platformTracer.enterSpan(name, async (span) => {
+		for (const key of Object.keys(attributes)) span.setAttribute(key, attributes[key]);
+		const store = traceAls.getStore();
+		const prevPlatformSpan = store?.platformSpan;
+		if (store) store.platformSpan = span;
+		try {
+			return await runOtelSpan(name, attributes, fn);
+		} finally {
+			if (store) store.platformSpan = prevPlatformSpan;
+		}
+	});
+}
+/** The OTEL half of withSpan() — no-op passthrough when no SDK is active. */
+async function runOtelSpan(name, attributes, fn) {
+	const tracer = await getTracer();
+	if (!tracer) return fn();
+	const api = await getOtelApi();
+	return tracer.startActiveSpan(name, { attributes }, async (span) => {
+		const prevSpanId = getSpanId();
+		updateSpanId(span.spanContext().spanId);
+		try {
+			const result = await fn();
+			span.setStatus({ code: api.SpanStatusCode.OK });
+			return result;
+		} catch (error) {
+			span.setStatus({ code: api.SpanStatusCode.ERROR });
+			if (error instanceof Error) span.recordException(error);
+			throw error;
+		} finally {
+			span.end();
+			updateSpanId(prevSpanId);
+		}
+	});
+}
+/**
+* Set an attribute on the current active span (if any).
+* Used for setting span attributes after span creation (e.g. timber.result on access spans).
+*/
+async function setSpanAttribute(key, value) {
+	const platformSpan = traceAls.getStore()?.platformSpan;
+	if (platformSpan) platformSpan.setAttribute(key, value);
+	const api = await getOtelApi();
+	if (!api) return;
+	const activeSpan = api.trace.getActiveSpan();
+	if (activeSpan) activeSpan.setAttribute(key, value);
+}
+/**
+* Add a span event to the current active span (if any).
+* Used for timber.cache HIT/MISS events — recorded as span events, not child spans.
+*/
+async function addSpanEvent(name, attributes) {
+	const api = await getOtelApi();
+	if (!api) return;
+	const activeSpan = api.trace.getActiveSpan();
+	if (activeSpan) activeSpan.addEvent(name, attributes);
+}
+/**
+* Fire-and-forget span event — no await, no microtask overhead.
+*
+* Used on the cache hot path where awaiting addSpanEvent creates an
+* unnecessary microtask per cache operation. If OTEL is not loaded yet,
+* the event is silently dropped (acceptable for diagnostics).
+*
+* See TIM-370 for perf motivation.
+*/
+function addSpanEventSync(name, attributes) {
+	if (!_otelApi) return;
+	const activeSpan = _otelApi.trace.getActiveSpan();
+	if (activeSpan) activeSpan.addEvent(name, attributes);
+}
+/**
+* Try to extract the OTEL trace ID from the current active span context.
+* Returns undefined if OTEL is not active or no span exists.
+*/
+async function getOtelTraceId() {
+	const api = await getOtelApi();
+	if (!api) return void 0;
+	const activeSpan = api.trace.getActiveSpan();
+	if (!activeSpan) return void 0;
+	const ctx = activeSpan.spanContext();
+	if (!ctx.traceId || ctx.traceId === "00000000000000000000000000000000") return;
+	return {
+		traceId: ctx.traceId,
+		spanId: ctx.spanId
+	};
+}
+//#endregion
+//#region src/server/error-formatter.ts
+/**
+* Error Formatter — rewrites SSR/RSC error messages to surface user code.
+*
+* When React or Vite throw errors during SSR, stack traces reference
+* vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
+* and mangled export names (`__vite_ssr_export_default__`). This module
+* rewrites error messages and stack traces to point at user code instead.
+*
+* Dev-only — in production, errors go through the structured logger
+* without formatting.
+*/
+/**
+* Patterns that identify internal Vite/RSC vendor paths in stack traces.
+* These are replaced with human-readable labels.
+*/
+var VENDOR_PATH_PATTERNS = [
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor_react-server-dom[^\s)]+/g,
+		replacement: "<react-server-dom>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor[^\s)]+/g,
+		replacement: "<rsc-vendor>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	}
+];
+/**
+* Patterns that identify Vite-mangled export names in error messages.
+*/
+var MANGLED_NAME_PATTERNS = [{
+	pattern: /__vite_ssr_export_default__/g,
+	replacement: "<default export>"
+}, {
+	pattern: /__vite_ssr_export_(\w+)__/g,
+	replacement: "<export $1>"
+}];
+/**
+* Rewrite an error's message and stack to replace internal Vite paths
+* and mangled names with human-readable labels.
+*/
+function formatSsrError(error) {
+	if (!(error instanceof Error)) return String(error);
+	let message = error.message;
+	let stack = error.stack ?? "";
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) message = message.replace(pattern, replacement);
+	for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) stack = stack.replace(pattern, replacement);
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) stack = stack.replace(pattern, replacement);
+	const hint = extractErrorHint(error.message);
+	const parts = [];
+	parts.push(message);
+	if (hint) parts.push(`  → ${hint}`);
+	const userFrames = extractUserFrames(stack);
+	if (userFrames.length > 0) {
+		parts.push("");
+		parts.push("  User code in stack:");
+		for (const frame of userFrames) parts.push(`    ${frame}`);
+	}
+	return parts.join("\n");
+}
+/**
+* Extract a human-readable hint from common React/RSC error messages.
+*
+* React error messages contain useful information but the surrounding
+* context (vendor paths, mangled names) obscures it. This extracts the
+* actionable part as a one-line hint.
+*/
+function extractErrorHint(message) {
+	if (message.match(/Functions cannot be passed directly to Client Components/)) {
+		const propMatch = message.match(/<[^>]*?\s(\w+)=\{function/);
+		if (propMatch) return `Prop "${propMatch[1]}" is a function — mark it "use server" or call it before passing`;
+		return "A function prop was passed to a Client Component — mark it \"use server\" or call it before passing";
+	}
+	if (message.includes("Objects are not valid as a React child")) return "An object was rendered as JSX children — convert to string or extract the value";
+	const nullRefMatch = message.match(/Cannot read propert(?:y|ies) of (undefined|null) \(reading '(\w+)'\)/);
+	if (nullRefMatch) return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;
+	const notFnMatch = message.match(/(\w+) is not a function/);
+	if (notFnMatch) return `"${notFnMatch[1]}" is not a function — check imports and exports`;
+	if (message.includes("Element type is invalid")) return "A component resolved to undefined/null — check default exports and import paths";
+	if (message.includes("Invalid hook call")) return "A hook was called outside of a React component render. If this is a 'use client' component, ensure the directive is at the very top of the file (before any imports) and that @vitejs/plugin-rsc is loaded correctly. Barrel re-exports from non-'use client' files do not propagate the directive.";
+	return null;
+}
+/**
+* Extract stack frames that reference user code (not node_modules,
+* not framework internals).
+*
+* Returns at most 5 frames to keep output concise.
+*/
+function extractUserFrames(stack) {
+	const lines = stack.split("\n");
+	const userFrames = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("at ")) continue;
+		if (trimmed.includes("node_modules") || trimmed.includes("<react-server-dom>") || trimmed.includes("<rsc-vendor>") || trimmed.includes("<vite-dep>") || trimmed.includes("node:internal")) continue;
+		userFrames.push(trimmed);
+		if (userFrames.length >= 5) break;
+	}
+	return userFrames;
+}
+//#endregion
+//#region src/server/default-logger.ts
+/**
+* DefaultLogger — human-readable stderr logging when no custom logger is configured.
+*
+* Ships as the fallback so production deployments always have error visibility,
+* even without an `instrumentation.ts` logger export. Output is one line per
+* event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+*
+* Format:
+*   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+*   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+*   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+*
+* Behavior:
+* - Suppressed entirely in dev mode (dev logging handles all output)
+* - `debug` suppressed unless TIMBER_DEBUG is set
+* - Replaced entirely when a custom logger is set via `setLogger()`
+*
+* See design/17-logging.md §"DefaultLogger"
+*/
+/**
+* Format data fields as `key=value` pairs for human-readable output.
+* - `error` key is serialized via formatSsrError for stack trace cleanup
+* - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+* - Other values are stringified inline
+*/
+function formatDataFields(data) {
+	if (!data) return "";
+	const parts = [];
+	let traceId;
+	for (const [key, value] of Object.entries(data)) {
+		if (key === "trace_id") {
+			traceId = typeof value === "string" ? value : String(value);
+			continue;
+		}
+		if (key === "error") {
+			parts.push(`error=${formatSsrError(value)}`);
+			continue;
+		}
+		if (value === void 0 || value === null) continue;
+		parts.push(`${key}=${value}`);
+	}
+	if (traceId) parts.push(`trace_id=${traceId.slice(0, 8)}`);
+	return parts.length > 0 ? "  " + parts.join("  ") : "";
+}
+/** Pad level string to fixed width for alignment. */
+function padLevel(level) {
+	return level.padEnd(5);
+}
+function createDefaultLogger() {
+	return {
+		error(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("ERROR")}  ${msg}${fields}\n`);
+		},
+		warn(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("WARN")}  ${msg}${fields}\n`);
+		},
+		info(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("INFO")}  ${msg}${fields}\n`);
+		},
+		debug(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("DEBUG")}  ${msg}${fields}\n`);
+		}
+	};
+}
+//#endregion
 //#region src/server/logger.ts
 /**
 * Logger — structured logging with environment-aware formatting.
@@ -1448,6 +1479,6 @@ function swallow(err, reason, opts) {
 	} catch {}
 }
 //#endregion
-export { setMatchedSegmentPath as A, addSpanEventSync as B, applyRequestHeaderOverlay as C, getSegmentParams as D, getSearchParams as E, getSetCookieHeaders as F, replaceTraceId as G, getOtelTraceId as H, getWaitUntil as I, withSpan as J, runWithTraceId as K, isDebug as L, setSegmentParams as M, getCookie as N, markResponseFlushed as O, getCookieJar as P, isDevMode as R, waitUntil as S, getHeaders as T, getSpanId as U, generateTraceId as V, getTraceId as W, RedirectSignal as _, logProxyError as a, redirect as b, logRequestReceived as c, logSwrRefetchFailed as d, logWaitUntilRejected as f, DenySignal as g, swallow as h, logMiddlewareShortCircuit as i, setMutableCookieContext as j, runWithRequestContext as k, logRouteError as l, setLogger as m, logCacheMiss as n, logRenderError as o, logWaitUntilUnsupported as p, setSpanAttribute as q, logMiddlewareError as r, logRequestCompleted as s, getLogger as t, logSlowRequest as u, RenderError as v, getHeader as w, redirectExternal as x, deny as y, addSpanEvent as z };
+export { isDenySignal as A, getSegmentParams as B, runWithTraceId as C, RedirectSignal as D, DenySignal as E, waitUntil as F, setSegmentParams as G, runWithRequestContext as H, applyRequestHeaderOverlay as I, getSetCookieHeaders as J, getCookie as K, getHeader as L, isSsrStreamError as M, redirect as N, RenderError as O, redirectExternal as P, getHeaders as R, replaceTraceId as S, withSpan as T, setMatchedSegmentPath as U, markResponseFlushed as V, setMutableCookieContext as W, isDevMode as X, isDebug as Y, getWaitUntil as Z, addSpanEventSync as _, logProxyError as a, getSpanId as b, logRequestReceived as c, logSwrRefetchFailed as d, logWaitUntilRejected as f, addSpanEvent as g, swallow as h, logMiddlewareShortCircuit as i, isRedirectSignal as j, deny as k, logRouteError as l, setLogger as m, logCacheMiss as n, logRenderError as o, logWaitUntilUnsupported as p, getCookieJar as q, logMiddlewareError as r, logRequestCompleted as s, getLogger as t, logSlowRequest as u, generateTraceId as v, setSpanAttribute as w, getTraceId as x, getOtelTraceId as y, getSearchParams as z };
 
-//# sourceMappingURL=logger-DDirEsn7.js.map
+//# sourceMappingURL=logger-uLBuGKDI.js.map