@timber-js/app 0.2.0-alpha.152 → 0.2.0-alpha.153

package/dist/_chunks/{actions-a0RczDnB.js → logger-DvmCWhN9.js}

@@ -1,9 +1,567 @@
-import { A as requestContextAls, D as withSpan, g as isDebug, j as revalidationAls } from "./logger-CM0clugc.js";
 import { t as _setGetSearchParamsFn } from "./define-CFmvb4Bt.js";
 import { t as _setGetSegmentParamsFn } from "./define-Bssfp6ot.js";
 import { n as assertValidCookieOptions, r as assertValidCookieValue, t as assertValidCookieName } from "./validation-taUkvA4Q.js";
-import { a as getWaitUntil, t as cache } from "./cache-api-Co-yI-gP.js";
 import { a as mergePreservedSearchParams, r as validateExternalRedirectUrl, t as assertRelativeRedirectPath } from "./href-validation-FiA_rToW.js";
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/server/als-registry.ts
+/**
+* Centralized AsyncLocalStorage registry for server-side per-request state.
+*
+* ALL ALS instances used by the server framework live here. Individual
+* modules (request-context.ts, tracing.ts, actions.ts, etc.) import from
+* this registry and re-export public accessor functions.
+*
+* Why: ALS instances require singleton semantics — if two copies of the
+* same ALS exist (one from a relative import, one from a barrel import,
+* or the same file re-evaluated by Vite after an HMR invalidation), one
+* module writes to its copy and another reads from an empty copy.
+* Centralizing ALS creation in a single module + anchoring each instance
+* on `globalThis` under a `Symbol.for(...)` key eliminates this class of
+* bug, including the Vite-dev case where module instance split would
+* otherwise hand two copies of this file out of a single evaluation cycle.
+*
+* The `timber-shims` plugin remaps `@timber-js/app/server` to src/ in
+* RSC and SSR environments so import-specifier paths converge here, and
+* the `globalThis[SYMBOL_FOR]` anchor below closes the remaining gap: any
+* second evaluation of this module picks up the ALS the first evaluation
+* already stored rather than instantiating a fresh one. Same pattern the
+* Cloudflare bindings ALS uses in `adapters/cloudflare.ts`.
+*
+* DO NOT create ALS instances outside this file. If you need a new ALS,
+* add it here and import from `./als-registry.js` in the consuming module.
+* Inside this file, always route through `getOrCreateAls(symbol)` — a raw
+* `new AsyncLocalStorage()` reintroduces the instance-split hazard.
+*
+* See design/18-build-system.md §"Module Singleton Strategy" and
+* §"Singleton State Registry". Regression test:
+* `tests/als-registry-singleton.test.ts`.
+*/
+/**
+* Return a process-wide singleton `AsyncLocalStorage` keyed by `symbol`.
+*
+* `Symbol.for(...)` keys live in the cross-realm symbol registry, and
+* `globalThis` is shared across every module evaluation inside the same
+* Node.js process. Together they give a stable anchor that survives
+* re-evaluation of this file — the second evaluation observes the
+* `globalThis[symbol]` slot already populated by the first and hands
+* back the identical ALS instance.
+*/
+function getOrCreateAls(symbol) {
+	const g = globalThis;
+	const existing = g[symbol];
+	if (existing instanceof AsyncLocalStorage) return existing;
+	const created = new AsyncLocalStorage();
+	g[symbol] = created;
+	return created;
+}
+/** @internal — import via request-context.ts public API */
+var requestContextAls = getOrCreateAls(Symbol.for("timber:request-context-als"));
+/** @internal — import via tracing.ts public API */
+var traceAls = getOrCreateAls(Symbol.for("timber:trace-als"));
+/** @internal — import via server-timing.ts public API */
+var timingAls = getOrCreateAls(Symbol.for("timber:timing-als"));
+/** @internal — import via actions.ts public API */
+var revalidationAls = getOrCreateAls(Symbol.for("timber:revalidation-als"));
+/** @internal — import via form-flash.ts public API */
+var formFlashAls = getOrCreateAls(Symbol.for("timber:form-flash-als"));
+/** @internal — import via early-hints-sender.ts public API */
+var earlyHintsSenderAls = getOrCreateAls(Symbol.for("timber:early-hints-sender-als"));
+/** @internal — import via waituntil-bridge.ts public API */
+var waitUntilAls = getOrCreateAls(Symbol.for("timber:wait-until-als"));
+//#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();
+}
+/**
+* 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 an OTEL span. If OTEL is not available, runs the function
+* directly without any span 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
+*/
+async function withSpan(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 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/debug.ts
+/**
+* Runtime debug flag for timber.js.
+*
+* Two distinct functions for two distinct security levels:
+*
+* ## `isDebug()` — server-side logging only
+*
+* Returns true when timber's debug/warning messages should be written to
+* stderr / the server console. This NEVER affects what is sent to the
+* client (no error details, no timing headers, no stack traces).
+*
+* Active when any of:
+* - `NODE_ENV !== 'production'` (standard dev mode)
+* - `TIMBER_DEBUG` env var is set to a truthy value at runtime
+* - `timber.config.ts` has `debug: true`
+*
+* ## `isDevMode()` — client-visible dev behavior
+*
+* Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything
+* that changes what clients can observe:
+* - Dev error pages with stack traces (fallback-error.ts)
+* - Detailed Server-Timing headers (pipeline.ts)
+* - Error messages in action INTERNAL_ERROR payloads (action-client.ts)
+* - Pipeline error handler wiring (Vite overlay)
+*
+* `isDevMode()` is statically replaced in production builds → the guarded
+* code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.
+*
+* Usage:
+*   In Cloudflare Workers wrangler.toml:
+*     [vars]
+*     TIMBER_DEBUG = "1"
+*
+*   In Node.js:
+*     TIMBER_DEBUG=1 node server.js
+*
+*   In timber.config.ts:
+*     export default { debug: true }
+*
+* See design/13-security.md for the security taxonomy.
+* See design/18-build-system.md for build pipeline details.
+*/
+/**
+* Check if the application is running in development mode.
+*
+* This is the ONLY function that should gate client-visible dev behavior:
+* - Dev error pages with stack traces
+* - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
+* - Error messages in action `INTERNAL_ERROR` payloads
+* - Pipeline error handler wiring (Vite overlay)
+*
+* Returns `process.env.NODE_ENV !== 'production'`, which is statically
+* replaced by the bundler in production builds. Code guarded by this
+* function is tree-shaken to zero bytes in production.
+*
+* TIMBER_DEBUG does NOT enable this — that would leak server internals
+* to clients. Use `isDebug()` for server-side-only logging.
+*/
+function isDevMode() {
+	return process.env.NODE_ENV !== "production";
+}
+/**
+* Config-level debug override. Set via `setDebugFromConfig()` during
+* initialization when timber.config.ts has `debug: true`.
+*/
+var _configDebug = false;
+/**
+* Check if timber debug logging is active (server-side only).
+*
+* Returns true if ANY of these conditions hold:
+* - NODE_ENV is not 'production' (standard dev mode)
+* - TIMBER_DEBUG environment variable is set to a truthy value at runtime
+* - timber.config.ts has `debug: true`
+*
+* This function controls ONLY server-side logging — messages written to
+* stderr or the server console. It NEVER affects client-visible behavior
+* (error pages, response headers, action payloads). For client-visible
+* behavior, use `isDevMode()`.
+*
+* The TIMBER_DEBUG check is deliberately written as a dynamic property
+* access so bundlers cannot statically replace it.
+*/
+function isDebug() {
+	if (process.env.NODE_ENV !== "production") return true;
+	if (_configDebug) return true;
+	return _readTimberDebugEnv();
+}
+/**
+* Read TIMBER_DEBUG from the environment at runtime.
+*
+* Extracted to a separate function to:
+* 1. Prevent bundler inlining (cross-module function calls are not inlined)
+* 2. Handle platforms where `process` may not exist (Cloudflare Workers)
+* 3. Support globalThis.__TIMBER_DEBUG for programmatic control
+*/
+function _readTimberDebugEnv() {
+	if (globalThis.__TIMBER_DEBUG) return true;
+	try {
+		const val = typeof process !== "undefined" && process.env ? process.env["TIMBER_DEBUG"] : void 0;
+		if (val && val !== "0" && val !== "false") return true;
+	} catch {}
+	return false;
+}
+//#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/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
 /**
 * Parse a Cookie header string into a Map of name → value pairs.
@@ -701,6 +1259,24 @@ var RedirectSignal = class extends Error {
 	}
 };
 /**
+* Returns true if the error is a framework control-flow signal (RedirectSignal
+* or DenySignal) rather than a genuine application error. Works both for direct
+* instances (RSC-side) and deserialized digest errors (SSR cross-boundary).
+*
+* See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
+*/
+function isControlFlowSignal(error) {
+	if (error instanceof DenySignal || error instanceof RedirectSignal) return true;
+	if (error && typeof error === "object") {
+		const digest = error.digest;
+		if (typeof digest === "string") try {
+			const parsed = JSON.parse(digest);
+			if (parsed && typeof parsed === "object") return parsed.type === "redirect" || parsed.type === "deny";
+		} catch {}
+	}
+	return false;
+}
+/**
 * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
 * Use `redirectExternal()` for external redirects with an allow-list.
 *
@@ -808,299 +1384,114 @@ function waitUntil(promise, adapter) {
 	}
 }
 //#endregion
-//#region src/server/form-data.ts
+//#region src/server/logger.ts
 /**
-* FormData preprocessing — schema-agnostic conversion of FormData to typed objects.
-*
-* FormData is all strings. Schema validation expects typed values. This module
-* bridges the gap with intelligent coercion that runs *before* schema validation.
+* Logger — structured logging with environment-aware formatting.
 *
-* Inspired by zod-form-data, but schema-agnostic — works with any Standard Schema
-* library (Zod, Valibot, ArkType).
+* timber.js ships a DefaultLogger that writes human-readable lines to stderr
+* in production. Users can export a custom logger from instrumentation.ts to
+* replace it with pino, winston, or any TimberLogger-compatible object.
 *
-* See design/08-forms-and-actions.md §"parseFormData() and coerce helpers"
+* See design/17-logging.md §"Production Logging"
 */
+var _logger = createDefaultLogger();
 /**
-* Convert FormData into a plain object with intelligent coercion.
-*
-* Handles:
-* - **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
-* - **Nested dot-paths**: `user.name=Alice` → `{ user: { name: "Alice" } }`
-* - **Empty strings → undefined**: Enables `.optional()` semantics in schemas
-* - **Empty Files → undefined**: File inputs with no selection become `undefined`
-* - **Strips `$ACTION_*` fields**: React's internal hidden fields are excluded
+* Set the user-provided logger. Called by the instrumentation loader
+* when it finds a `logger` export in instrumentation.ts. Replaces
+* the DefaultLogger entirely.
 */
-function parseFormData(formData) {
-	const flat = {};
-	for (const key of new Set(formData.keys())) {
-		if (key.startsWith("$ACTION_")) continue;
-		if (DANGEROUS_KEYS.has(key)) continue;
-		const processed = formData.getAll(key).map(normalizeValue);
-		if (processed.length === 1) flat[key] = processed[0];
-		else flat[key] = processed.filter((v) => v !== void 0);
-	}
-	return expandDotPaths(flat);
+function setLogger(logger) {
+	_logger = logger;
 }
 /**
-* Normalize a single FormData entry value.
-* - Empty strings → undefined (enables .optional() semantics)
-* - Empty File objects (no selection) → undefined
-* - Everything else passes through as-is
+* Get the current logger. Always non-null — returns DefaultLogger when
+* no custom logger is configured.
 */
-function normalizeValue(value) {
-	if (typeof value === "string") return value === "" ? void 0 : value;
-	if (value instanceof File && value.size === 0 && value.name === "") return;
-	return value;
+function getLogger() {
+	return _logger;
 }
 /**
-* Expand dot-notation keys into nested objects.
-* `{ "user.name": "Alice", "user.age": "30" }` → `{ user: { name: "Alice", age: "30" } }`
-*
-* Keys without dots are left as-is. Bracket notation (e.g. `items[0]`) is NOT
-* supported — use dot notation (`items.0`) instead.
+* Inject trace_id and span_id into log data for log–trace correlation.
+* Always injects trace_id (never undefined). Injects span_id only when OTEL is active.
 */
-function expandDotPaths(flat) {
-	const result = {};
-	let hasDotPaths = false;
-	for (const key of Object.keys(flat)) if (key.includes(".")) {
-		hasDotPaths = true;
-		break;
+function withTraceContext(data) {
+	const store = getTraceStore();
+	const enriched = { ...data };
+	if (store) {
+		enriched.trace_id = store.traceId;
+		if (store.spanId) enriched.span_id = store.spanId;
 	}
-	if (!hasDotPaths) return flat;
-	for (const [key, value] of Object.entries(flat)) {
-		const parts = key.split(".");
-		if (parts.some((p) => DANGEROUS_KEYS.has(p))) continue;
-		if (parts.length === 1) {
-			result[parts[0]] = value;
-			continue;
-		}
-		let current = result;
-		for (let i = 0; i < parts.length - 1; i++) {
-			const part = parts[i];
-			if (current[part] === void 0 || current[part] === null) current[part] = {};
-			if (typeof current[part] !== "object" || current[part] instanceof File) current[part] = {};
-			current = current[part];
-		}
-		current[parts[parts.length - 1]] = value;
-	}
-	return result;
+	return enriched;
 }
-var DANGEROUS_KEYS = new Set(["__proto__"]);
-/**
-* Schema-agnostic coercion primitives for common FormData patterns.
-*
-* These are plain transform functions — they compose with any schema library's
-* `transform`/`preprocess` pipeline:
-*
-* ```ts
-* // Zod
-* z.preprocess(coerce.number, z.number())
-* // Valibot
-* v.pipe(v.unknown(), v.transform(coerce.number), v.number())
-* ```
-*/
-var coerce = {
-	/**
-	* Coerce a string to a number.
-	* - `"42"` → `42`
-	* - `"3.14"` → `3.14`
-	* - `""` / `undefined` / `null` → `undefined`
-	* - Non-numeric strings → `undefined` (schema validation will catch this)
-	*/
-	number(value) {
-		if (value === void 0 || value === null || value === "") return void 0;
-		if (typeof value === "number") return value;
-		if (typeof value !== "string") return void 0;
-		const num = Number(value);
-		if (Number.isNaN(num)) return void 0;
-		return num;
-	},
-	/**
-	* Coerce a checkbox value to a boolean.
-	* HTML checkboxes submit "on" when checked and are absent when unchecked.
-	* - `"on"` / any truthy string → `true`
-	* - `undefined` / `null` / `""` → `false`
-	*/
-	checkbox(value) {
-		if (value === void 0 || value === null || value === "") return false;
-		if (typeof value === "boolean") return value;
-		return typeof value === "string" && value.length > 0;
-	},
-	/**
-	* Parse a JSON string into an object.
-	* - Valid JSON string → parsed object
-	* - `""` / `undefined` / `null` → `undefined`
-	* - Invalid JSON → `undefined` (schema validation will catch this)
-	*/
-	json(value) {
-		if (value === void 0 || value === null || value === "") return void 0;
-		if (typeof value !== "string") return value;
-		try {
-			return JSON.parse(value);
-		} catch {
-			return;
-		}
-	},
-	/**
-	* Coerce a date string to a Date object.
-	* Handles `<input type="date">` (`"2024-01-15"`), `<input type="datetime-local">`
-	* (`"2024-01-15T10:30"`), and full ISO 8601 strings.
-	* - Valid date string → `Date`
-	* - `""` / `undefined` / `null` → `undefined`
-	* - Invalid date strings → `undefined` (schema validation will catch this)
-	* - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`
-	*/
-	date(value) {
-		if (value === void 0 || value === null || value === "") return void 0;
-		if (value instanceof Date) return value;
-		if (typeof value !== "string") return void 0;
-		const date = new Date(value);
-		if (Number.isNaN(date.getTime())) return void 0;
-		const ymdMatch = value.match(/^(\d{4})-(\d{2})-(\d{2})/);
-		if (ymdMatch) {
-			const inputYear = Number(ymdMatch[1]);
-			const inputMonth = Number(ymdMatch[2]);
-			const inputDay = Number(ymdMatch[3]);
-			const isUTC = value.length === 10 || value.endsWith("Z");
-			const parsedYear = isUTC ? date.getUTCFullYear() : date.getFullYear();
-			const parsedMonth = isUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1;
-			const parsedDay = isUTC ? date.getUTCDate() : date.getDate();
-			if (inputYear !== parsedYear || inputMonth !== parsedMonth || inputDay !== parsedDay) return;
-		}
-		return date;
-	},
-	/**
-	* Create a File coercion function with optional size and mime type validation.
-	* Returns the File if valid, `undefined` otherwise.
-	*
-	* ```ts
-	* // Basic — just checks it's a real File
-	* z.preprocess(coerce.file(), z.instanceof(File))
-	*
-	* // With constraints
-	* z.preprocess(
-	*   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
-	*   z.instanceof(File)
-	* )
-	* ```
-	*/
-	file(options) {
-		return (value) => {
-			if (value === void 0 || value === null || value === "") return void 0;
-			if (!(value instanceof File)) return void 0;
-			if (value.size === 0 && value.name === "") return void 0;
-			if (options?.maxSize !== void 0 && value.size > options.maxSize) return;
-			if (options?.accept !== void 0 && !options.accept.includes(value.type)) return;
-			return value;
-		};
-	}
-};
-//#endregion
-//#region src/server/actions.ts
-/**
-* Server action primitives: revalidatePath, revalidateTag, and the action handler.
-*
-* - revalidatePath(path) re-renders the route at that path and returns the RSC
-*   flight payload for inline reconciliation.
-* - revalidateTag(tag) invalidates timber.cache entries by tag.
-*
-* Both are callable from anywhere on the server — actions, API routes, handlers.
-*
-* The action handler processes incoming action requests, validates CSRF,
-* enforces body limits, executes the action, and returns the response
-* (with piggybacked RSC payload if revalidatePath was called).
-*
-* See design/08-forms-and-actions.md
-*/
-/**
-* Get the current revalidation state. Throws if called outside an action context.
-* @internal
-*/
-function getRevalidationState() {
-	const state = revalidationAls.getStore();
-	if (!state) throw new Error("revalidatePath/revalidateTag called outside of a server action context. These functions can only be called during action execution.");
-	return state;
+/** Log a completed request. Level: info. */
+function logRequestCompleted(data) {
+	_logger.info("request completed", withTraceContext(data));
 }
-/**
-* Re-render the route at `path` and include the RSC flight payload in the
-* action response. The client reconciles inline — no separate fetch needed.
-*
-* Can be called from server actions, API routes, or any server-side context.
-*
-* @param path - The path to re-render (e.g. '/dashboard', '/todos').
-*/
-function revalidatePath(path) {
-	const state = getRevalidationState();
-	if (!state.paths.includes(path)) state.paths.push(path);
+/** Log request received. Level: debug. */
+function logRequestReceived(data) {
+	_logger.debug("request received", withTraceContext(data));
 }
-/**
-* Invalidate all timber.cache entries tagged with `tag`.
-* Does not return a payload — the next request for an invalidated entry re-executes.
-*
-* @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
-*/
-function revalidateTag(tag) {
-	const state = getRevalidationState();
-	if (!state.tags.includes(tag)) state.tags.push(tag);
+/** Log a slow request warning. Level: warn. */
+function logSlowRequest(data) {
+	_logger.warn("slow request exceeded threshold", withTraceContext(data));
+}
+/** Log middleware short-circuit. Level: debug. */
+function logMiddlewareShortCircuit(data) {
+	_logger.debug("middleware short-circuited", withTraceContext(data));
+}
+/** Log unhandled error in middleware phase. Level: error. */
+function logMiddlewareError(data) {
+	if (isControlFlowSignal(data.error)) return;
+	_logger.error("unhandled error in middleware phase", withTraceContext(data));
+}
+/** Log unhandled render-phase error. Level: error. */
+function logRenderError(data) {
+	if (isControlFlowSignal(data.error)) return;
+	_logger.error("unhandled render-phase error", withTraceContext(data));
+}
+/** Log proxy.ts uncaught error. Level: error. */
+function logProxyError(data) {
+	_logger.error("proxy.ts threw uncaught error", withTraceContext(data));
+}
+/** Log unhandled error in route handler. Level: error. */
+function logRouteError(data) {
+	if (isControlFlowSignal(data.error)) return;
+	_logger.error("unhandled route handler error", withTraceContext(data));
+}
+/** Log waitUntil() adapter missing (once at startup). Level: warn. */
+function logWaitUntilUnsupported() {
+	_logger.warn("adapter does not support waitUntil()");
+}
+/** Log waitUntil() promise rejection. Level: warn. */
+function logWaitUntilRejected(data) {
+	_logger.warn("waitUntil() promise rejected", withTraceContext(data));
+}
+/** Log staleWhileRevalidate refetch failure. Level: warn. */
+function logSwrRefetchFailed(data) {
+	_logger.warn("staleWhileRevalidate refetch failed", withTraceContext(data));
+}
+/** Log cache miss. Level: debug. */
+function logCacheMiss(data) {
+	_logger.debug("timber.cache MISS", withTraceContext(data));
 }
 /**
-* Execute a server action and process revalidation.
+* Log an intentionally swallowed error. Provides observability into catch
+* blocks that are deliberately empty — the error is consumed, never rethrown.
 *
-* 1. Sets up revalidation state
-* 2. Calls the action function
-* 3. Processes revalidateTag calls (invalidates cache entries)
-* 4. Processes revalidatePath calls (re-renders and captures RSC payload)
-* 5. Returns the action result + optional RSC payload
+* Default level: `warn` in dev (so the overlay surfaces patterns), `debug`
+* in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`
+* to override.
 *
-* @param actionFn - The server action function to execute.
-* @param args - Arguments to pass to the action.
-* @param config - Handler configuration (cache handler, renderer).
+* **Infallible** — swallow() itself never throws, even if the logger is
+* broken. A thrown swallow would turn a benign catch into a crash.
 */
-async function executeAction(actionFn, args, config = {}, spanMeta) {
-	const state = {
-		paths: [],
-		tags: []
-	};
-	let actionResult;
-	let redirectTo;
-	let redirectStatus;
-	await revalidationAls.run(state, async () => {
-		try {
-			actionResult = await withSpan("timber.action", {
-				...spanMeta?.actionFile ? { "timber.action_file": spanMeta.actionFile } : {},
-				...spanMeta?.actionName ? { "timber.action_name": spanMeta.actionName } : {}
-			}, () => actionFn(...args));
-		} catch (error) {
-			if (error instanceof RedirectSignal) {
-				redirectTo = error.location;
-				redirectStatus = error.status;
-			} else throw error;
-		}
-	});
-	if (state.tags.length > 0) await Promise.all(state.tags.map((tag) => cache.invalidate({ tag })));
-	let revalidation;
-	if (state.paths.length > 0 && config.renderer) {
-		const path = state.paths[0];
-		try {
-			revalidation = await config.renderer(path);
-		} catch (renderError) {
-			if (renderError instanceof RedirectSignal) {
-				redirectTo = renderError.location;
-				redirectStatus = renderError.status;
-			} else if (renderError instanceof DenySignal) console.error(`[timber] revalidatePath dropped — target middleware denied (status ${renderError.status})`);
-			else console.error("[timber] revalidatePath render failed:", renderError);
-		}
-	}
-	return {
-		actionResult,
-		revalidation,
-		...redirectTo ? {
-			redirectTo,
-			redirectStatus
-		} : {}
-	};
+function swallow(err, reason, opts) {
+	try {
+		const level = opts?.level ?? (isDevMode() ? "warn" : "debug");
+		_logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));
+	} catch {}
 }
 //#endregion
-export { setSegmentParams as C, getSetCookieHeaders as E, setMutableCookieContext as S, getCookieJar as T, getSearchParams as _, parseFormData as a, runWithRequestContext as b, RenderError as c, redirectExternal as d, waitUntil as f, getHeaders as g, getHeader as h, coerce as i, deny as l, applyRequestHeaderOverlay as m, revalidatePath as n, DenySignal as o, RedirectType as p, revalidateTag as r, RedirectSignal as s, executeAction as t, redirect as u, getSegmentParams as v, getCookie as w, setMatchedSegmentPath as x, markResponseFlushed as y };
+export { revalidationAls as $, runWithRequestContext as A, addSpanEvent as B, RedirectType as C, getSearchParams as D, getHeaders as E, getCookieJar as F, getTraceId as G, generateTraceId as H, getSetCookieHeaders as I, setSpanAttribute as J, replaceTraceId as K, getWaitUntil as L, setMutableCookieContext as M, setSegmentParams as N, getSegmentParams as O, getCookie as P, requestContextAls as Q, isDebug as R, waitUntil as S, getHeader as T, getOtelTraceId as U, addSpanEventSync as V, getSpanId as W, earlyHintsSenderAls as X, withSpan as Y, formFlashAls as Z, RedirectSignal as _, logProxyError as a, redirect as b, logRequestReceived as c, logSwrRefetchFailed as d, timingAls as et, logWaitUntilRejected as f, DenySignal as g, swallow as h, logMiddlewareShortCircuit as i, setMatchedSegmentPath as j, markResponseFlushed as k, logRouteError as l, setLogger as m, logCacheMiss as n, logRenderError as o, logWaitUntilUnsupported as p, runWithTraceId as q, logMiddlewareError as r, logRequestCompleted as s, getLogger as t, logSlowRequest as u, RenderError as v, applyRequestHeaderOverlay as w, redirectExternal as x, deny as y, isDevMode as z };
 
-//# sourceMappingURL=actions-a0RczDnB.js.map
+//# sourceMappingURL=logger-DvmCWhN9.js.map