@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/dist/_chunks/tracing-DvKLzCFa.js

@@ -0,0 +1,329 @@
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#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/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),
+* one module writes to its copy and another reads from an empty copy.
+* Centralizing ALS creation in a single module eliminates this class of bug.
+*
+* The `timber-shims` plugin ensures `@timber-js/app/server` resolves to
+* src/ in RSC and SSR environments, so all import paths converge here.
+*
+* 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.
+*
+* See design/18-build-system.md §"Module Singleton Strategy" and
+* §"Singleton State Registry".
+*/
+/** @internal — import via request-context.ts public API */
+var requestContextAls = new AsyncLocalStorage();
+/** @internal — import via tracing.ts public API */
+var traceAls = new AsyncLocalStorage();
+/** @internal — import via server-timing.ts public API */
+var timingAls = new AsyncLocalStorage();
+/** @internal — import via actions.ts public API */
+var revalidationAls = new AsyncLocalStorage();
+/** @internal — import via form-flash.ts public API */
+var formFlashAls = new AsyncLocalStorage();
+/** @internal — import via early-hints-sender.ts public API */
+var earlyHintsSenderAls = new AsyncLocalStorage();
+/** @internal — import via waituntil-bridge.ts public API */
+var waitUntilAls = new AsyncLocalStorage();
+//#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
+export { waitUntilAls as _, getSpanId as a, replaceTraceId as c, withSpan as d, earlyHintsSenderAls as f, timingAls as g, revalidationAls as h, getOtelTraceId as i, runWithTraceId as l, requestContextAls as m, addSpanEventSync as n, getTraceId as o, formFlashAls as p, generateTraceId as r, getTraceStore as s, addSpanEvent as t, setSpanAttribute as u, isDebug as v, isDevMode as y };
+
+//# sourceMappingURL=tracing-DvKLzCFa.js.map

package/dist/_chunks/tracing-DvKLzCFa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-DvKLzCFa.js","names":[],"sources":["../../src/server/debug.ts","../../src/server/als-registry.ts","../../src/server/tracing.ts"],"sourcesContent":["/**\n * Runtime debug flag for timber.js.\n *\n * Two distinct functions for two distinct security levels:\n *\n * ## `isDebug()` — server-side logging only\n *\n * Returns true when timber's debug/warning messages should be written to\n * stderr / the server console. This NEVER affects what is sent to the\n * client (no error details, no timing headers, no stack traces).\n *\n * Active when any of:\n * - `NODE_ENV !== 'production'` (standard dev mode)\n * - `TIMBER_DEBUG` env var is set to a truthy value at runtime\n * - `timber.config.ts` has `debug: true`\n *\n * ## `isDevMode()` — client-visible dev behavior\n *\n * Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything\n * that changes what clients can observe:\n * - Dev error pages with stack traces (fallback-error.ts)\n * - Detailed Server-Timing headers (pipeline.ts)\n * - Error messages in action INTERNAL_ERROR payloads (action-client.ts)\n * - Pipeline error handler wiring (Vite overlay)\n *\n * `isDevMode()` is statically replaced in production builds → the guarded\n * code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.\n *\n * Usage:\n *   In Cloudflare Workers wrangler.toml:\n *     [vars]\n *     TIMBER_DEBUG = \"1\"\n *\n *   In Node.js:\n *     TIMBER_DEBUG=1 node server.js\n *\n *   In timber.config.ts:\n *     export default { debug: true }\n *\n * See design/13-security.md for the security taxonomy.\n * See design/18-build-system.md for build pipeline details.\n */\n\n// ─── Dev Mode (client-visible) ──────────────────────────────────────────────\n\n/**\n * Check if the application is running in development mode.\n *\n * This is the ONLY function that should gate client-visible dev behavior:\n * - Dev error pages with stack traces\n * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)\n * - Error messages in action `INTERNAL_ERROR` payloads\n * - Pipeline error handler wiring (Vite overlay)\n *\n * Returns `process.env.NODE_ENV !== 'production'`, which is statically\n * replaced by the bundler in production builds. Code guarded by this\n * function is tree-shaken to zero bytes in production.\n *\n * TIMBER_DEBUG does NOT enable this — that would leak server internals\n * to clients. Use `isDebug()` for server-side-only logging.\n */\nexport function isDevMode(): boolean {\n  return process.env.NODE_ENV !== 'production';\n}\n\n// ─── Debug Flag (server-side logging only) ──────────────────────────────────\n\n/**\n * Config-level debug override. Set via `setDebugFromConfig()` during\n * initialization when timber.config.ts has `debug: true`.\n */\nlet _configDebug = false;\n\n/**\n * Set the debug flag from timber.config.ts.\n * Called during handler initialization.\n */\nexport function setDebugFromConfig(debug: boolean): void {\n  _configDebug = debug;\n}\n\n/**\n * Check if timber debug logging is active (server-side only).\n *\n * Returns true if ANY of these conditions hold:\n * - NODE_ENV is not 'production' (standard dev mode)\n * - TIMBER_DEBUG environment variable is set to a truthy value at runtime\n * - timber.config.ts has `debug: true`\n *\n * This function controls ONLY server-side logging — messages written to\n * stderr or the server console. It NEVER affects client-visible behavior\n * (error pages, response headers, action payloads). For client-visible\n * behavior, use `isDevMode()`.\n *\n * The TIMBER_DEBUG check is deliberately written as a dynamic property\n * access so bundlers cannot statically replace it.\n */\nexport function isDebug(): boolean {\n  // Fast path: dev mode (statically replaced to `true` in dev, `false` in prod)\n  if (process.env.NODE_ENV !== 'production') return true;\n\n  // Config override\n  if (_configDebug) return true;\n\n  // Runtime env var check — uses dynamic access to prevent static replacement.\n  // In production builds, process.env.NODE_ENV is statically replaced, but\n  // TIMBER_DEBUG must survive as a runtime check. The dynamic key access\n  // pattern ensures the bundler treats this as opaque.\n  return _readTimberDebugEnv();\n}\n\n/**\n * Read TIMBER_DEBUG from the environment at runtime.\n *\n * Extracted to a separate function to:\n * 1. Prevent bundler inlining (cross-module function calls are not inlined)\n * 2. Handle platforms where `process` may not exist (Cloudflare Workers)\n * 3. Support globalThis.__TIMBER_DEBUG for programmatic control\n */\nfunction _readTimberDebugEnv(): boolean {\n  // globalThis override — useful for programmatic control and testing\n  if ((globalThis as Record<string, unknown>).__TIMBER_DEBUG) return true;\n\n  // process.env — works in Node.js and platforms that polyfill process\n  try {\n    const key = 'TIMBER_DEBUG';\n    const val =\n      typeof process !== 'undefined' && process.env\n        ? (process.env as Record<string, string | undefined>)[key]\n        : undefined;\n    if (val && val !== '0' && val !== 'false') return true;\n  } catch {\n    // process may not exist or env may throw — safe to ignore\n  }\n\n  return false;\n}\n","/**\n * Centralized AsyncLocalStorage registry for server-side per-request state.\n *\n * ALL ALS instances used by the server framework live here. Individual\n * modules (request-context.ts, tracing.ts, actions.ts, etc.) import from\n * this registry and re-export public accessor functions.\n *\n * Why: ALS instances require singleton semantics — if two copies of the\n * same ALS exist (one from a relative import, one from a barrel import),\n * one module writes to its copy and another reads from an empty copy.\n * Centralizing ALS creation in a single module eliminates this class of bug.\n *\n * The `timber-shims` plugin ensures `@timber-js/app/server` resolves to\n * src/ in RSC and SSR environments, so all import paths converge here.\n *\n * DO NOT create ALS instances outside this file. If you need a new ALS,\n * add it here and import from `./als-registry.js` in the consuming module.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport type { DebugComponentEntry } from './rsc-entry/helpers.js';\n\n// ─── Request Context ──────────────────────────────────────────────────────\n// Used by: request-context.ts (getHeaders(), getCookies(), getSearchParams())\n// Design doc: design/04-authorization.md\n\n/** @internal — import via request-context.ts public API */\nexport const requestContextAls = new AsyncLocalStorage<RequestContextStore>();\n\nexport interface RequestContextStore {\n  /** Incoming request headers (read-only view). */\n  headers: Headers;\n  /** Raw cookie header string, parsed lazily into a Map on first access. */\n  cookieHeader: string;\n  /** Lazily-parsed cookie map (mutable — reflects write-overlay from set()). */\n  parsedCookies?: Map<string, string>;\n  /** Original (pre-overlay) frozen headers, kept for overlay merging. */\n  originalHeaders: Headers;\n  /**\n   * Raw URLSearchParams for the current request.\n   * To get typed parsed params, import a search params definition and\n   * call `.parse(searchParams())`.\n   */\n  searchParams: URLSearchParams;\n  /**\n   * Raw search string from the request URL (e.g. \"?foo=bar&baz=1\").\n   * Available synchronously for use in `redirect()` with `preserveSearchParams`.\n   */\n  searchString: string;\n  /**\n   * Coerced segment params for the current request.\n   * Set by the pipeline after route matching and param coercion, before\n   * middleware and rendering. Pages and layouts read params via\n   * `getSegmentParams()` instead of receiving them as a prop.\n   *\n   * See design/07-routing.md §\"params.ts — Convention File for Typed Params\"\n   */\n  segmentParams?: Record<string, string | string[]>;\n  /**\n   * The matched segment path (e.g. '/(browse)/[artistSlug]/[year]').\n   * Includes route groups and parallel slots — uniquely identifies the\n   * segment in the route tree. Set by the pipeline alongside segmentParams.\n   * Used by getSegmentParams() for dev-mode validation.\n   * See design/41-global-params.md §Runtime Validation\n   */\n  matchedSegmentPath?: string;\n  /**\n   * Per-slot coerced segment params, keyed by the slot's full tree path\n   * (e.g. '/(browse)/@shows/[artistSlug]/[...year]').\n   *\n   * Each slot walks its own segment tree and may interpret URL parts\n   * differently from the main route (e.g. catch-all vs dynamic). This\n   * map stores slot-specific params so getSegmentParams(segmentPath)\n   * returns the correct types for slot pages.\n   *\n   * See design/07-routing.md §\"Parallel Slot Params\"\n   */\n  slotParamsMap?: Map<string, Record<string, string | string[]>>;\n  /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */\n  cookieJar: Map<string, CookieEntry>;\n  /** Whether the response has flushed (headers committed). */\n  flushed: boolean;\n  /** Whether the current context allows cookie mutation. */\n  mutableContext: boolean;\n  /**\n   * Set by AccessGate or PageDenyBoundary when a DenySignal is caught\n   * server-side (inside the React tree, before React Flight sees it).\n   * The pipeline reads this after render to set the HTTP status code.\n   * See TIM-666.\n   */\n  denyStatus?: number;\n  /**\n   * Dev-only: getter for the current request's RSC debug components.\n   * Set by renderRoute() so onPipelineError can include component tree\n   * context for render-phase errors without module-level shared state.\n   */\n  debugComponentsGetter?: () => DebugComponentEntry[];\n}\n\n/** A single outgoing cookie entry in the cookie jar. */\nexport interface CookieEntry {\n  name: string;\n  value: string;\n  options: import('./cookie-context.js').CookieOptions;\n}\n\n// ─── Tracing ──────────────────────────────────────────────────────────────\n// Used by: tracing.ts (getTraceId(), getSpanId())\n// Design doc: design/17-logging.md\n\nexport interface TraceStore {\n  /** 32-char lowercase hex trace ID (OTEL or UUID fallback). */\n  traceId: string;\n  /** OTEL span ID if available, undefined otherwise. */\n  spanId?: string;\n}\n\n/** @internal — import via tracing.ts public API */\nexport const traceAls = new AsyncLocalStorage<TraceStore>();\n\n// ─── Server-Timing ────────────────────────────────────────────────────────\n// Used by: server-timing.ts (recordTiming(), withTiming())\n// Design doc: (dev-only performance instrumentation)\n\nexport interface TimingStore {\n  entries: import('./server-timing.js').TimingEntry[];\n}\n\n/** @internal — import via server-timing.ts public API */\nexport const timingAls = new AsyncLocalStorage<TimingStore>();\n\n// ─── Revalidation ─────────────────────────────────────────────────────────\n// Used by: actions.ts (revalidatePath(), revalidateTag())\n// Design doc: design/08-forms-and-actions.md\n\nexport interface RevalidationState {\n  /** Paths to re-render (populated by revalidatePath calls). */\n  paths: string[];\n  /** Tags to invalidate (populated by revalidateTag calls). */\n  tags: string[];\n}\n\n/** @internal — import via actions.ts public API */\nexport const revalidationAls = new AsyncLocalStorage<RevalidationState>();\n\n// ─── Form Flash ───────────────────────────────────────────────────────────\n// Used by: form-flash.ts (getFormFlash())\n// Design doc: design/08-forms-and-actions.md §\"No-JS Error Round-Trip\"\n\n/** @internal — import via form-flash.ts public API */\nexport const formFlashAls = new AsyncLocalStorage<import('./form-flash.js').FormFlashData>();\n\n// ─── Early Hints Sender ──────────────────────────────────────────────────\n// Used by: early-hints-sender.ts (sendEarlyHints103())\n// Design doc: design/02-rendering-pipeline.md §\"Early Hints (103)\"\n\n/** Function that sends Link header values as a 103 Early Hints response. */\nexport type EarlyHintsSenderFn = (links: string[]) => void;\n\n/** @internal — import via early-hints-sender.ts public API */\nexport const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();\n\n// ─── waitUntil Bridge ────────────────────────────────────────────────────\n// Used by: waituntil-bridge.ts (waitUntil())\n// Design doc: design/11-platform.md §\"waitUntil()\"\n\n/** Function that extends the request lifecycle with a background promise. */\nexport type WaitUntilFn = (promise: Promise<unknown>) => void;\n\n/** @internal — import via waituntil-bridge.ts public API */\nexport const waitUntilAls = new AsyncLocalStorage<WaitUntilFn>();\n","/**\n * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.\n *\n * getTraceId() is always available in server code (middleware, access, components, actions).\n * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,\n * or a crypto.randomUUID()-derived fallback otherwise.\n *\n * See design/17-logging.md §\"trace_id is Always Set\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { traceAls, type TraceStore } from './als-registry.js';\n\n// Re-export the TraceStore type for public API consumers.\nexport type { TraceStore } from './als-registry.js';\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns the current request's trace ID — always a 32-char lowercase hex string.\n *\n * With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).\n * Without OTEL: crypto.randomUUID() with hyphens stripped.\n *\n * Throws if called outside a request context (no ALS store).\n */\nexport function getTraceId(): string {\n  const store = traceAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] getTraceId() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.traceId;\n}\n\n/**\n * Returns the current OTEL span ID if available, undefined otherwise.\n */\nexport function getSpanId(): string | undefined {\n  return traceAls.getStore()?.spanId;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Generate a 32-char lowercase hex ID from crypto.randomUUID().\n * Same format as OTEL trace IDs — zero-friction upgrade path.\n */\nexport function generateTraceId(): string {\n  return randomUUID().replace(/-/g, '');\n}\n\n/**\n * Run a callback within a trace context. Used by the pipeline to establish\n * per-request ALS scope.\n */\nexport function runWithTraceId<T>(id: string, fn: () => T): T {\n  return traceAls.run({ traceId: id }, fn);\n}\n\n/**\n * Replace the trace ID in the current ALS store. Used when OTEL creates\n * a root span and we want to switch from the UUID fallback to the real\n * OTEL trace ID.\n */\nexport function replaceTraceId(newTraceId: string, newSpanId?: string): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.traceId = newTraceId;\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Update the span ID in the current ALS store. Used when entering a new\n * OTEL span to keep log–trace correlation accurate.\n */\nexport function updateSpanId(newSpanId: string | undefined): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Get the current trace store, or undefined if outside a request context.\n * Framework-internal — use getTraceId()/getSpanId() in user code.\n */\nexport function getTraceStore(): TraceStore | undefined {\n  return traceAls.getStore();\n}\n\n// ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────\n\n/**\n * Initialize a minimal OTEL SDK in dev mode so spans are recorded and\n * fed to the DevSpanProcessor for dev log output.\n *\n * If the user already configured an OTEL SDK in register(), we add\n * our DevSpanProcessor alongside theirs. If no SDK is configured,\n * we create a BasicTracerProvider with our processor.\n *\n * Only called in dev mode — zero overhead in production.\n */\nexport async function initDevTracing(\n  config: import('../dev-tools/logger.js').DevLoggerConfig\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  let DevSpanProcessor: typeof import('../dev-tools/instrumentation.js').DevSpanProcessor;\n  let BasicTracerProvider: typeof import('@opentelemetry/sdk-trace-base').BasicTracerProvider;\n  let AsyncLocalStorageContextManager: typeof import('@opentelemetry/context-async-hooks').AsyncLocalStorageContextManager;\n\n  try {\n    ({ DevSpanProcessor } = await import('../dev-tools/instrumentation.js'));\n    ({ BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base'));\n    ({ AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks'));\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    console.warn(`[timber] Dev tracing disabled — failed to load OTEL packages:\\n  ${msg}`);\n    return;\n  }\n\n  const processor = new DevSpanProcessor(config);\n\n  // Register a context manager so OTEL can propagate the active span\n  // across async boundaries. Without this, startActiveSpan can't make\n  // spans \"active\" — child spans get random trace IDs and getActiveSpan()\n  // returns undefined.\n  const contextManager = new AsyncLocalStorageContextManager();\n  contextManager.enable();\n  api.context.setGlobalContextManager(contextManager);\n\n  // Create a minimal TracerProvider with our DevSpanProcessor.\n  // If the user also configures an SDK in register(), their provider\n  // will coexist — the global provider set last wins for new tracers,\n  // but our processor captures all spans from the timber.js tracer.\n  const provider = new BasicTracerProvider({\n    spanProcessors: [processor],\n  });\n  api.trace.setGlobalTracerProvider(provider);\n\n  // Reset cached tracer so next getTracer() picks up the new provider\n  _tracer = undefined;\n}\n\n// ─── OTEL Span Helpers ───────────────────────────────────────────────────\n\n/**\n * Attempt to get the @opentelemetry/api tracer. Returns undefined if the\n * package is not installed or no SDK is registered.\n *\n * timber.js depends on @opentelemetry/api as the vendor-neutral interface.\n * The API is a no-op by default — spans are only emitted when the developer\n * initializes an SDK in register().\n */\nlet _otelApi: typeof import('@opentelemetry/api') | null | undefined;\n\nasync function getOtelApi(): Promise<typeof import('@opentelemetry/api') | null> {\n  if (_otelApi === undefined) {\n    try {\n      _otelApi = await import('@opentelemetry/api');\n    } catch {\n      _otelApi = null;\n    }\n  }\n  return _otelApi;\n}\n\n/** OTEL tracer instance, lazily created. */\nlet _tracer: import('@opentelemetry/api').Tracer | null | undefined;\n\n/**\n * Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.\n */\nexport async function getTracer(): Promise<import('@opentelemetry/api').Tracer | null> {\n  if (_tracer === undefined) {\n    const api = await getOtelApi();\n    if (api) {\n      _tracer = api.trace.getTracer('timber.js');\n    } else {\n      _tracer = null;\n    }\n  }\n  return _tracer;\n}\n\n/**\n * Run a function within an OTEL span. If OTEL is not available, runs the function\n * directly without any span overhead.\n *\n * Automatically:\n * - Creates the span as a child of the current context\n * - Updates the ALS span ID for log–trace correlation\n * - Ends the span when the function completes\n * - Records exceptions on error\n */\nexport async function withSpan<T>(\n  name: string,\n  attributes: Record<string, string | number | boolean>,\n  fn: () => T | Promise<T>\n): Promise<T> {\n  const tracer = await getTracer();\n  if (!tracer) {\n    return fn();\n  }\n\n  const api = (await getOtelApi())!;\n  return tracer.startActiveSpan(name, { attributes }, async (span) => {\n    const prevSpanId = getSpanId();\n    updateSpanId(span.spanContext().spanId);\n    try {\n      const result = await fn();\n      span.setStatus({ code: api.SpanStatusCode.OK });\n      return result;\n    } catch (error) {\n      span.setStatus({ code: api.SpanStatusCode.ERROR });\n      if (error instanceof Error) {\n        span.recordException(error);\n      }\n      throw error;\n    } finally {\n      span.end();\n      updateSpanId(prevSpanId);\n    }\n  });\n}\n\n/**\n * Set an attribute on the current active span (if any).\n * Used for setting span attributes after span creation (e.g. timber.result on access spans).\n */\nexport async function setSpanAttribute(\n  key: string,\n  value: string | number | boolean\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.setAttribute(key, value);\n  }\n}\n\n/**\n * Add a span event to the current active span (if any).\n * Used for timber.cache HIT/MISS events — recorded as span events, not child spans.\n */\nexport async function addSpanEvent(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Fire-and-forget span event — no await, no microtask overhead.\n *\n * Used on the cache hot path where awaiting addSpanEvent creates an\n * unnecessary microtask per cache operation. If OTEL is not loaded yet,\n * the event is silently dropped (acceptable for diagnostics).\n *\n * See TIM-370 for perf motivation.\n */\nexport function addSpanEventSync(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): void {\n  // Fast path: if OTEL API hasn't been loaded yet, skip entirely.\n  // _otelApi is undefined (not yet loaded), null (failed to load), or the module.\n  if (!_otelApi) return;\n\n  const activeSpan = _otelApi.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Try to extract the OTEL trace ID from the current active span context.\n * Returns undefined if OTEL is not active or no span exists.\n */\nexport async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {\n  const api = await getOtelApi();\n  if (!api) return undefined;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (!activeSpan) return undefined;\n\n  const ctx = activeSpan.spanContext();\n  // OTEL uses \"0000000000000000\" as invalid trace IDs\n  if (!ctx.traceId || ctx.traceId === '00000000000000000000000000000000') {\n    return undefined;\n  }\n\n  return { traceId: ctx.traceId, spanId: ctx.spanId };\n}\n"],"mappings":"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"}

package/dist/_chunks/{use-query-states-D5KaffOK.js → use-query-states-C9G6LP0F.js}

@@ -1,21 +1,5 @@
+import { t as getSearchParamsDefinition } from "./registry-BI9cgCt7.js";
 import { useQueryStates } from "nuqs";
-//#region src/search-params/registry.ts
-var registry = /* @__PURE__ */ new Map();
-/**
-* Register a route's search params definition.
-* Called by the generated route manifest loader when a route's modules load.
-*/
-function registerSearchParams(route, definition) {
-	registry.set(route, definition);
-}
-/**
-* Look up a route's search params definition.
-* Returns undefined if the route hasn't been loaded yet.
-*/
-function getSearchParams(route) {
-	return registry.get(route);
-}
-//#endregion
 //#region src/client/use-query-states.ts
 /**
 * useQueryStates — client-side hook for URL-synced search params.
@@ -69,13 +53,16 @@ function useQueryStates$1(codecsOrRoute, _options, urlKeys) {
 	let codecs;
 	let resolvedUrlKeys = urlKeys;
 	if (typeof codecsOrRoute === "string") {
-		const definition = getSearchParams(codecsOrRoute);
+		const definition = getSearchParamsDefinition(codecsOrRoute);
 		if (!definition) throw new Error(`useQueryStates('${codecsOrRoute}'): no search params registered for this route. Either the route has no search-params.ts file, or it hasn't been loaded yet. For cross-route usage, import the definition explicitly.`);
 		codecs = definition.codecs;
 		resolvedUrlKeys = definition.urlKeys;
 	} else codecs = codecsOrRoute;
 	const bridged = bridgeCodecs(codecs);
 	const nuqsOptions = {};
+	if (_options?.shallow !== void 0) nuqsOptions.shallow = _options.shallow;
+	if (_options?.scroll !== void 0) nuqsOptions.scroll = _options.scroll;
+	if (_options?.history !== void 0) nuqsOptions.history = _options.history;
 	if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) nuqsOptions.urlKeys = resolvedUrlKeys;
 	let values;
 	let setValues;
@@ -104,6 +91,6 @@ function bindUseQueryStates(definition) {
 	};
 }
 //#endregion
-export { registerSearchParams as i, useQueryStates$1 as n, getSearchParams as r, bindUseQueryStates as t };
+export { useQueryStates$1 as n, bindUseQueryStates as t };
 
-//# sourceMappingURL=use-query-states-D5KaffOK.js.map
+//# sourceMappingURL=use-query-states-C9G6LP0F.js.map

package/dist/_chunks/use-query-states-C9G6LP0F.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-query-states-C9G6LP0F.js","names":[],"sources":["../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { SingleParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '../search-params/define.js';\nimport { getSearchParamsDefinition } from '../search-params/registry.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {\n  return {\n    parse: (v: string) => codec.parse(v),\n    serialize: (v: T) => codec.serialize(v) ?? '',\n    defaultValue: codec.parse(undefined) as T,\n    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),\n  };\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  // Route-string overload: resolve codecs from the registry\n  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n  let resolvedUrlKeys = urlKeys;\n  if (typeof codecsOrRoute === 'string') {\n    const definition = getSearchParamsDefinition(codecsOrRoute);\n    if (!definition) {\n      throw new Error(\n        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +\n          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +\n          `For cross-route usage, import the definition explicitly.`\n      );\n    }\n    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };\n    resolvedUrlKeys = definition.urlKeys;\n  } else {\n    codecs = codecsOrRoute;\n  }\n\n  const bridged = bridgeCodecs(codecs);\n\n  // Forward hook-level options (shallow, scroll, history) to nuqs.\n  // These become the default for all setter calls from this hook instance.\n  // Per-call options in setParams(values, opts) override these defaults.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;\n  if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;\n  if (_options?.history !== undefined) nuqsOptions.history = _options.history;\n  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(partial as any, nuqsSetOptions);\n  };\n\n  return [values as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA8BA,SAAS,YAAe,OAAmE;AACzF,QAAO;EACL,QAAQ,MAAc,MAAM,MAAM,EAAE;EACpC,YAAY,MAAS,MAAM,UAAU,EAAE,IAAI;EAC3C,cAAc,MAAM,MAAM,KAAA,EAAU;EACpC,KAAK,GAAM,MAAS,MAAM,UAAU,EAAE,KAAK,MAAM,UAAU,EAAE;EAC9D;;;;;AAMH,SAAS,aAAgD,QAEtD;CACD,MAAM,SAA4E,EAAE;AACpF,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CAEnC,QAAO,OAAO,YAAY,OAAO,KAAgB;AAEnD,QAAO;;;;;;;;;;;;;;;;;;;AAsBT,SAAgB,iBACd,eACA,UACA,SACmB;CAEnB,IAAI;CACJ,IAAI,kBAAkB;AACtB,KAAI,OAAO,kBAAkB,UAAU;EACrC,MAAM,aAAa,0BAA0B,cAAc;AAC3D,MAAI,CAAC,WACH,OAAM,IAAI,MACR,mBAAmB,cAAc,uLAGlC;AAEH,WAAS,WAAW;AACpB,oBAAkB,WAAW;OAE7B,UAAS;CAGX,MAAM,UAAU,aAAa,OAAO;CAMpC,MAAM,cAAmB,EAAE;AAC3B,KAAI,UAAU,YAAY,KAAA,EAAW,aAAY,UAAU,SAAS;AACpE,KAAI,UAAU,WAAW,KAAA,EAAW,aAAY,SAAS,SAAS;AAClE,KAAI,UAAU,YAAY,KAAA,EAAW,aAAY,UAAU,SAAS;AACpE,KAAI,mBAAmB,OAAO,KAAK,gBAAgB,CAAC,SAAS,EAC3D,aAAY,UAAU;CAGxB,IAAI;CACJ,IAAI;AACJ,KAAI;AACF,GAAC,QAAQ,aAAa,eAAmB,SAAS,YAAY;UACvD,KAAK;AACZ,MACE,eAAe,SACf,qEAAqE,KAAK,IAAI,QAAQ,CAEtF,OAAM,IAAI,MACR,6JAED;AAEH,QAAM;;CAMR,MAAM,aAA2B,SAAS,eAAgB;EACxD,MAAM,iBAA0C,EAAE;AAClD,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAC3E,MAAI,YAAY,WAAW,KAAA,EAAW,gBAAe,SAAS,WAAW;AACzE,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAEtE,YAAU,SAAgB,eAAe;;AAGhD,QAAO,CAAC,QAAa,UAAU;;;;;;AASjC,SAAgB,mBACd,YACqD;AACrD,SAAQ,YAAiC;AACvC,SAAO,iBAAkB,WAAW,QAAQ,SAAS,WAAW,QAAQ"}

package/dist/_chunks/use-segment-params-CtIAjqK0.js

@@ -0,0 +1,185 @@
+import { t as __exportAll } from "../index.js";
+import { a as _setCurrentParams, l as currentParams, n as getSsrData } from "./ssr-data-m9-cNEIw.js";
+import React, { createElement } from "react";
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current route params and pathname, updated atomically
+* with the RSC tree on each navigation. This replaces the previous
+* useSyncExternalStore approach for useSegmentParams() and usePathname(),
+* which suffered from a timing gap: the new tree could commit before
+* the external store re-renders fired, causing a frame where both
+* old and new active states were visible simultaneously.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (useParams, usePathname) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+* Symbol.for keys. The RSC client bundler can duplicate this module
+* across chunks (browser-entry graph + client-reference graph). With
+* ESM output, each chunk gets its own module scope — module-level
+* variables would create separate singleton instances per chunk.
+* globalThis guarantees a single instance regardless of duplication.
+*
+* This workaround will be removed when Rolldown ships `format: 'app'`
+* (module registry format that deduplicates like webpack/Turbopack).
+* See design/27-chunking-strategy.md.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*
+* Context instances are stored on globalThis (NOT in module-level
+* variables) because the ESM bundler can duplicate this module across
+* chunks. Module-level variables would create separate instances per
+* chunk — the provider in NavigationRoot (index chunk) would use
+* context A while the consumer in usePendingNavigation (shared chunk)
+* reads from context B. globalThis guarantees a single instance.
+*
+* See design/27-chunking-strategy.md §"Singleton Safety"
+*
+* NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an
+* internal helper — the public hook is `usePendingNavigation()` in
+* use-pending-navigation.ts.
+*/
+var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
+var PENDING_CTX_KEY = Symbol.for("__timber_pending_nav_ctx");
+function getOrCreateContext() {
+	const existing = globalThis[NAV_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[NAV_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by useSegmentParams() and usePathname().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Navigation state communicated between the router and renderRoot.
+*
+* The router calls setNavigationState() before renderRoot(). The
+* renderRoot callback reads via getNavigationState() to create the
+* NavigationProvider with the correct params/pathname.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+*
+* Stored on globalThis (like the context instances above) because the
+* router lives in one chunk while renderRoot lives in another. Module-
+* level variables would be separate per chunk.
+*/
+var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
+function _getNavStateStore() {
+	const g = globalThis;
+	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
+		params: {},
+		pathname: "/"
+	} };
+	return g[NAV_STATE_KEY];
+}
+function setNavigationState(state) {
+	_getNavStateStore().current = state;
+}
+function getNavigationState() {
+	return _getNavStateStore().current;
+}
+/**
+* Separate context for the in-flight navigation URL. Provided by
+* NavigationRoot (urgent useState), consumed by usePendingNavigation
+* and TopLoader. Per-link pending state uses useOptimistic instead
+* (see link-pending-store.ts).
+*
+* Uses globalThis via Symbol.for for the same reason as NavigationContext
+* above — the bundler may duplicate this module across chunks, and module-
+* level variables would create separate context instances.
+*/
+function getOrCreatePendingContext() {
+	const existing = globalThis[PENDING_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[PENDING_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the pending navigation URL from context.
+* Returns null during SSR (no provider) or in the RSC environment.
+*/
+function usePendingNavigationUrl() {
+	const ctx = getOrCreatePendingContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+//#endregion
+//#region src/client/use-segment-params.ts
+var use_segment_params_exports = /* @__PURE__ */ __exportAll({
+	setCurrentParams: () => setCurrentParams,
+	useSegmentParams: () => useSegmentParams
+});
+/**
+* Set the current route params in the module-level store.
+*
+* Called by the router on each navigation. This updates the fallback
+* snapshot used by tests and by the hook when called outside a React
+* component (no NavigationContext available).
+*
+* On the client, the primary reactivity path is NavigationContext —
+* the router calls setNavigationState() then renderRoot() which wraps
+* the element in NavigationProvider. setCurrentParams is still called
+* for the module-level fallback.
+*
+* During SSR, params are also available via getSsrData().params
+* (ALS-backed).
+*/
+function setCurrentParams(params) {
+	_setCurrentParams(params);
+}
+function useSegmentParams(_segmentPath) {
+	try {
+		const navContext = useNavigationContext();
+		if (navContext !== null) return navContext.params;
+	} catch {}
+	return getSsrData()?.params ?? currentParams;
+}
+//#endregion
+export { getNavigationState as a, usePendingNavigationUrl as c, NavigationProvider as i, useSegmentParams as n, setNavigationState as o, use_segment_params_exports as r, useNavigationContext as s, setCurrentParams as t };
+
+//# sourceMappingURL=use-segment-params-CtIAjqK0.js.map