@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/server/tracing.ts

@@ -252,6 +252,29 @@ export async function addSpanEvent(
   }
 }
 
+/**
+ * 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.
+ */
+export function addSpanEventSync(
+  name: string,
+  attributes?: Record<string, string | number | boolean>
+): void {
+  // Fast path: if OTEL API hasn't been loaded yet, skip entirely.
+  // _otelApi is undefined (not yet loaded), null (failed to load), or the module.
+  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.

package/src/server/tree-builder.ts

@@ -46,10 +46,13 @@ export type SlotElements = Map<string, ReactElement>;
 export interface TreeBuilderConfig {
   /** The matched segment chain from root to leaf. */
   segments: SegmentNode[];
-  /** Route params extracted by the matcher (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
-  /** Parsed search params (typed or URLSearchParams). */
-  searchParams: unknown;
+  /**
+   * Route params extracted by the matcher (catch-all segments produce string[]).
+   * @deprecated Params are now accessed via rawSegmentParams() from ALS.
+   * This field is kept for backward compatibility but is no longer used
+   * by the tree builder itself.
+   */
+  params?: Record<string, string | string[]>;
   /** Loads a route file's module. */
   loadModule: ModuleLoader;
   /** React.createElement or equivalent. */
@@ -77,9 +80,7 @@ export interface TreeBuilderConfig {
  * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
  */
 export interface AccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  accessFn: (ctx: { params: Record<string, string | string[]> }) => unknown;
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
@@ -98,12 +99,19 @@ export interface AccessGateProps {
 /**
  * Framework-injected slot access gate component.
  * On denial, renders denied.tsx → default.tsx → null instead of failing the page.
+ *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * SlotAccessGate can forward DenySignal.data as dangerouslyPassData
+ * and slotName as the slot prop after catching the signal.
  */
 export interface SlotAccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-  deniedFallback: ReactElement | null;
+  accessFn: (ctx: { params: Record<string, string | string[]> }) => unknown;
+  /** The denied.tsx component (not a pre-built element). null if no denied.tsx exists. */
+  DeniedComponent: ((...args: unknown[]) => unknown) | null;
+  /** Slot directory name without @ prefix (e.g. "admin", "sidebar"). */
+  slotName: string;
+  /** createElement function for building elements dynamically. */
+  createElement: CreateElement;
   defaultFallback: ReactElement | null;
   children: ReactElement;
 }
@@ -113,7 +121,8 @@ export interface SlotAccessGateProps {
  * Wraps content with status-code error boundary handling.
  */
 export interface ErrorBoundaryProps {
-  fallbackComponent: ReactElement | null;
+  fallbackComponent?: ReactElement | null;
+  fallbackElement?: ReactElement | null;
   status?: number;
   children: ReactElement;
 }
@@ -143,8 +152,7 @@ export interface TreeBuildResult {
  * Parallel slots are resolved at each layout level and composed as named props.
  */
 export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult> {
-  const { segments, params, searchParams, loadModule, createElement, errorBoundaryComponent } =
-    config;
+  const { segments, loadModule, createElement, errorBoundaryComponent } = config;
 
   if (segments.length === 0) {
     throw new Error('[timber] buildElementTree: empty segment chain');
@@ -168,8 +176,8 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     );
   }
 
-  // Build the page element with params and searchParams props
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  // Build the page element — params are accessed via rawSegmentParams() from ALS
+  let element: ReactElement = createElement(PageComponent, {});
 
   // Build tree bottom-up: wrap page, then walk segments from leaf to root
   for (let i = segments.length - 1; i >= 0; i--) {
@@ -190,8 +198,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
       const accessFn = accessModule.default as AccessGateProps['accessFn'];
       element = createElement('timber:access-gate', {
         accessFn,
-        params,
-        searchParams,
         segmentName: segment.segmentName,
         children: element,
       } satisfies AccessGateProps);
@@ -211,8 +217,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
           for (const [slotName, slotNode] of segment.slots) {
             slotProps[slotName] = await buildSlotElement(
               slotNode,
-              params,
-              searchParams,
               loadModule,
               createElement,
               errorBoundaryComponent
@@ -222,8 +226,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
 
         element = createElement(LayoutComponent, {
           ...slotProps,
-          params,
-          searchParams,
           children: element,
         });
       }
@@ -243,8 +245,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
  */
 async function buildSlotElement(
   slotNode: SegmentNode,
-  params: Record<string, string | string[]>,
-  searchParams: unknown,
   loadModule: ModuleLoader,
   createElement: CreateElement,
   errorBoundaryComponent: unknown
@@ -261,10 +261,10 @@ async function buildSlotElement(
 
   // If no page, render default.tsx or null
   if (!PageComponent) {
-    return DefaultComponent ? createElement(DefaultComponent, { params, searchParams }) : null;
+    return DefaultComponent ? createElement(DefaultComponent, {}) : null;
   }
 
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  let element: ReactElement = createElement(PageComponent, {});
 
   // Wrap in error boundaries
   element = await wrapWithErrorBoundaries(
@@ -280,27 +280,19 @@ async function buildSlotElement(
     const accessModule = await loadModule(slotNode.access);
     const accessFn = accessModule.default as SlotAccessGateProps['accessFn'];
 
-    // Load denied.tsx
+    // Load denied.tsx — pass component (not pre-built element) so
+    // SlotAccessGate can forward DenySignal.data dynamically. See TIM-488.
     const deniedModule = slotNode.denied ? await loadModule(slotNode.denied) : null;
-    const DeniedComponent = deniedModule?.default as
-      | ((...args: unknown[]) => ReactElement)
-      | undefined;
-
-    const deniedFallback = DeniedComponent
-      ? createElement(DeniedComponent, {
-          slot: slotNode.segmentName.replace(/^@/, ''),
-          dangerouslyPassData: undefined,
-        })
-      : null;
-    const defaultFallback = DefaultComponent
-      ? createElement(DefaultComponent, { params, searchParams })
-      : null;
+    const DeniedComponent =
+      (deniedModule?.default as ((...args: unknown[]) => ReactElement) | undefined) ?? null;
+
+    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
 
     element = createElement('timber:slot-access-gate', {
       accessFn,
-      params,
-      searchParams,
-      deniedFallback,
+      DeniedComponent,
+      slotName: slotNode.segmentName.replace(/^@/, ''),
+      createElement,
       defaultFallback,
       children: element,
     } satisfies SlotAccessGateProps);
@@ -311,6 +303,19 @@ async function buildSlotElement(
 
 // ─── Error Boundary Wrapping ─────────────────────────────────────────────────
 
+/** MDX/markdown extensions — these are server components that cannot be passed as function props. */
+const MDX_EXTENSIONS = new Set(['mdx', 'md']);
+
+/**
+ * Check if a route file is an MDX/markdown file based on its extension.
+ * MDX components are server components by default and cannot cross the
+ * RSC→client boundary as function props. They must be pre-rendered as
+ * elements and passed as fallbackElement instead of fallbackComponent.
+ */
+function isMdxFile(file: RouteFile): boolean {
+  return MDX_EXTENSIONS.has(file.extension);
+}
+
 /**
  * Wrap an element with error boundaries from a segment's status-code files.
  *
@@ -320,6 +325,12 @@ async function buildSlotElement(
  *   3. error.tsx (general error boundary)
  *
  * This creates the fallback chain described in design/10-error-handling.md.
+ *
+ * MDX status files are server components and cannot be passed as function
+ * props to TimberErrorBoundary (a 'use client' component). Instead, they
+ * are pre-rendered as elements and passed as fallbackElement. The error
+ * boundary renders the element directly when an error is caught.
+ * See TIM-503.
  */
 async function wrapWithErrorBoundaries(
   segment: SegmentNode,
@@ -340,11 +351,18 @@ async function wrapWithErrorBoundaries(
           const mod = await loadModule(file);
           const Component = mod.default;
           if (Component) {
-            element = createElement(errorBoundaryComponent, {
-              fallbackComponent: Component,
-              status,
-              children: element,
-            } satisfies ErrorBoundaryProps);
+            const boundaryProps = isMdxFile(file)
+              ? ({
+                  fallbackElement: createElement(Component, { status }),
+                  status,
+                  children: element,
+                } satisfies ErrorBoundaryProps)
+              : ({
+                  fallbackComponent: Component,
+                  status,
+                  children: element,
+                } satisfies ErrorBoundaryProps);
+            element = createElement(errorBoundaryComponent, boundaryProps);
           }
         }
       }
@@ -356,25 +374,41 @@ async function wrapWithErrorBoundaries(
         const mod = await loadModule(file);
         const Component = mod.default;
         if (Component) {
-          element = createElement(errorBoundaryComponent, {
-            fallbackComponent: Component,
-            status: key === '4xx' ? 400 : 500, // category marker
-            children: element,
-          } satisfies ErrorBoundaryProps);
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          const boundaryProps = isMdxFile(file)
+            ? ({
+                fallbackElement: createElement(Component, {}),
+                status: categoryStatus,
+                children: element,
+              } satisfies ErrorBoundaryProps)
+            : ({
+                fallbackComponent: Component,
+                status: categoryStatus,
+                children: element,
+              } satisfies ErrorBoundaryProps);
+          element = createElement(errorBoundaryComponent, boundaryProps);
         }
       }
     }
   }
 
   // Wrap with error.tsx (outermost — catches anything not matched by status files)
+  // Note: error.tsx/error.mdx receives { error, digest, reset } props.
+  // MDX error files are pre-rendered without those props (they're static content).
   if (segment.error) {
     const errorModule = await loadModule(segment.error);
     const ErrorComponent = errorModule.default;
     if (ErrorComponent) {
-      element = createElement(errorBoundaryComponent, {
-        fallbackComponent: ErrorComponent,
-        children: element,
-      } satisfies ErrorBoundaryProps);
+      const boundaryProps = isMdxFile(segment.error)
+        ? ({
+            fallbackElement: createElement(ErrorComponent, {}),
+            children: element,
+          } satisfies ErrorBoundaryProps)
+        : ({
+            fallbackComponent: ErrorComponent,
+            children: element,
+          } satisfies ErrorBoundaryProps);
+      element = createElement(errorBoundaryComponent, boundaryProps);
     }
   }
 

package/src/server/types.ts

@@ -22,8 +22,7 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  segmentParams: Record<string, string | string[]>;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
 }
@@ -37,7 +36,6 @@ export interface RouteContext {
 
 export interface AccessContext {
   params: Record<string, string | string[]>;
-  searchParams: unknown;
 }
 
 export interface Metadata {

package/src/server/version-skew.ts

@@ -0,0 +1,104 @@
+/**
+ * Version Skew Detection — graceful recovery when stale clients hit new deployments.
+ *
+ * When a new version of the app is deployed, clients with open tabs still have
+ * the old JavaScript bundle. Without version skew handling, these stale clients
+ * will experience:
+ *
+ * 1. Server action calls that crash (action IDs are content-hashed)
+ * 2. Chunk load failures (old filenames gone from CDN)
+ * 3. RSC payload mismatches (component references differ between builds)
+ *
+ * This module implements deployment ID comparison:
+ * - A per-build deployment ID is generated at build time (see build-manifest.ts)
+ * - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
+ * - The server compares it against the current build's ID
+ * - On mismatch: signal the client to reload (not crash)
+ *
+ * The deployment ID is always-on in production. Dev mode skips the check
+ * (HMR handles code updates without full reloads).
+ *
+ * See design/25-production-deployments.md, TIM-446
+ */
+
+// ─── Constants ───────────────────────────────────────────────────
+
+/** Header sent by the client with every RSC/action request. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/** Response header that signals the client to do a full page reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The current build's deployment ID. Set at startup from the manifest init
+ * module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
+ */
+let currentDeploymentId: string | null = null;
+
+/**
+ * Set the current deployment ID. Called once at server startup from the
+ * manifest init module. In dev mode this is never called (deployment ID
+ * checks are skipped).
+ */
+export function setDeploymentId(id: string): void {
+  currentDeploymentId = id;
+}
+
+/**
+ * Get the current deployment ID. Returns null in dev mode.
+ */
+export function getDeploymentId(): string | null {
+  return currentDeploymentId;
+}
+
+// ─── Skew Detection ──────────────────────────────────────────────
+
+/** Result of a version skew check. */
+export interface SkewCheckResult {
+  /** Whether the client's deployment ID matches the server's. */
+  ok: boolean;
+  /** The client's deployment ID (null if header not sent — e.g., initial page load). */
+  clientId: string | null;
+}
+
+/**
+ * Check if a request's deployment ID matches the current build.
+ *
+ * Returns `{ ok: true }` when:
+ * - Dev mode (no deployment ID set — HMR handles updates)
+ * - No deployment ID header (initial page load, non-RSC request)
+ * - Deployment IDs match
+ *
+ * Returns `{ ok: false }` when:
+ * - Client sends a deployment ID that differs from the current build
+ */
+export function checkVersionSkew(req: Request): SkewCheckResult {
+  // Dev mode — no deployment ID checks (HMR handles updates)
+  if (!currentDeploymentId) {
+    return { ok: true, clientId: null };
+  }
+
+  const clientId = req.headers.get(DEPLOYMENT_ID_HEADER);
+
+  // No header — initial page load or non-RSC request. Always OK.
+  if (!clientId) {
+    return { ok: true, clientId: null };
+  }
+
+  // Compare deployment IDs
+  if (clientId === currentDeploymentId) {
+    return { ok: true, clientId };
+  }
+
+  return { ok: false, clientId };
+}
+
+/**
+ * Apply version skew reload headers to a response.
+ * Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
+ */
+export function applyReloadHeaders(headers: Headers): void {
+  headers.set(RELOAD_HEADER, '1');
+}

package/src/server/waituntil-bridge.ts

@@ -18,7 +18,10 @@ import { waitUntilAls } from './als-registry.js';
  * Called by generated entry points (Nitro node-server/bun, Cloudflare)
  * to bind the platform's lifecycle extension for the request duration.
  */
-export function runWithWaitUntil<T>(waitUntilFn: (promise: Promise<unknown>) => void, fn: () => T): T {
+export function runWithWaitUntil<T>(
+  waitUntilFn: (promise: Promise<unknown>) => void,
+  fn: () => T
+): T {
   return waitUntilAls.run(waitUntilFn, fn);
 }
 

package/src/shared/merge-search-params.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared utility for merging preserved search params into a target URL.
+ *
+ * Used by both <Link> (client) and redirect() (server). Extracted to a shared
+ * module to avoid importing client code ('use client') from server modules.
+ */
+
+/**
+ * Merge preserved search params from the current URL into a target href.
+ *
+ * When `preserve` is `true`, all current search params are merged.
+ * When `preserve` is a `string[]`, only the named params are merged.
+ *
+ * The target href's own search params take precedence — preserved params
+ * are only added if the target doesn't already define them.
+ *
+ * @param targetHref - The resolved target href (may already contain query string)
+ * @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+ * @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+ * @returns The target href with preserved search params merged in
+ */
+export function mergePreservedSearchParams(
+  targetHref: string,
+  currentSearch: string,
+  preserve: true | string[]
+): string {
+  const currentParams = new URLSearchParams(currentSearch);
+  if (currentParams.size === 0) return targetHref;
+
+  // Split target into path and existing query
+  const qIdx = targetHref.indexOf('?');
+  const targetPath = qIdx >= 0 ? targetHref.slice(0, qIdx) : targetHref;
+  const targetParams = new URLSearchParams(qIdx >= 0 ? targetHref.slice(qIdx + 1) : '');
+
+  // Collect params to preserve (that aren't already in the target)
+  const merged = new URLSearchParams(targetParams);
+  for (const [key, value] of currentParams) {
+    // Only preserve if: (a) not already in target, and (b) included in preserve list
+    if (!targetParams.has(key)) {
+      if (preserve === true || preserve.includes(key)) {
+        merged.append(key, value);
+      }
+    }
+  }
+
+  const qs = merged.toString();
+  return qs ? `${targetPath}?${qs}` : targetPath;
+}

package/src/shims/navigation-client.ts

@@ -18,7 +18,7 @@
 
 // Hooks — imported from the public barrel for module singleton consistency.
 export {
-  useParams,
+  useSegmentParams,
   usePathname,
   useSearchParams,
   useRouter,

package/src/shims/navigation.ts

@@ -8,7 +8,7 @@
 
 // Hooks (client-side — imported from public barrel for module singleton)
 export {
-  useParams,
+  useSegmentParams,
   usePathname,
   useSearchParams,
   useRouter,

package/src/utils/state-machine.ts

@@ -0,0 +1,111 @@
+/**
+ * Tiny typed state machine utility.
+ *
+ * Enforces discriminated-union states, typed transitions with runtime
+ * guards, subscribe for external store integration, and assertPhase
+ * for function entry guards.
+ *
+ * Designed for 3–5 state consumers (stream transforms, client navigation,
+ * build phase sequencing). No async, no hierarchy, no history.
+ *
+ * Performance: send() is one object lookup + one function call.
+ * Equivalent cost to a boolean check after V8 inlining.
+ */
+
+/** A state machine instance with typed state and events. */
+export interface Machine<TState extends { phase: string }, TEvent extends { type: string }> {
+  /** Current state (discriminated union — narrowed by phase). */
+  readonly state: TState;
+
+  /** Transition with runtime guard. Throws on invalid source+event pair. */
+  send(event: TEvent): void;
+
+  /** Subscribe to state changes. Returns unsubscribe function. */
+  subscribe(listener: (state: TState) => void): () => void;
+
+  /** Throw if not in the expected phase. Entry guard for functions. */
+  assertPhase<P extends TState['phase']>(phase: P): void;
+}
+
+/**
+ * Transition map: `transitions[phase][eventType]` returns the next state.
+ *
+ * Each handler receives the current state (narrowed by phase context)
+ * and the event, returning the new state.
+ */
+export type TransitionMap<TState extends { phase: string }, TEvent extends { type: string }> = {
+  [P in TState['phase']]?: {
+    [E in TEvent['type']]?: (
+      state: Extract<TState, { phase: P }>,
+      event: Extract<TEvent, { type: E }>
+    ) => TState;
+  };
+};
+
+export interface MachineConfig<TState extends { phase: string }, TEvent extends { type: string }> {
+  initial: TState;
+  transitions: TransitionMap<TState, TEvent>;
+  /** Fires after every valid transition. Use for side effects. */
+  onTransition?: (prev: TState, next: TState, event: TEvent) => void;
+}
+
+/**
+ * Create a state machine from a config.
+ *
+ * @example
+ * ```ts
+ * type State = { phase: 'idle' } | { phase: 'running'; pid: number };
+ * type Event = { type: 'START'; pid: number } | { type: 'STOP' };
+ *
+ * const m = createMachine<State, Event>({
+ *   initial: { phase: 'idle' },
+ *   transitions: {
+ *     idle: { START: (_s, e) => ({ phase: 'running', pid: e.pid }) },
+ *     running: { STOP: () => ({ phase: 'idle' }) },
+ *   },
+ * });
+ * ```
+ */
+export function createMachine<TState extends { phase: string }, TEvent extends { type: string }>(
+  config: MachineConfig<TState, TEvent>
+): Machine<TState, TEvent> {
+  let current: TState = config.initial;
+  const listeners = new Set<(state: TState) => void>();
+
+  return {
+    get state() {
+      return current;
+    },
+
+    send(event: TEvent): void {
+      const phaseHandlers = config.transitions[current.phase as TState['phase']];
+      const handler = phaseHandlers?.[event.type as TEvent['type']] as
+        | ((state: TState, event: TEvent) => TState)
+        | undefined;
+
+      if (!handler) {
+        throw new Error(`[state-machine] Invalid transition: ${current.phase} + ${event.type}`);
+      }
+
+      const prev = current;
+      current = handler(prev, event);
+
+      config.onTransition?.(prev, current, event);
+
+      for (const listener of listeners) {
+        listener(current);
+      }
+    },
+
+    subscribe(listener: (state: TState) => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    assertPhase<P extends TState['phase']>(phase: P): void {
+      if (current.phase !== phase) {
+        throw new Error(`[state-machine] Expected phase "${phase}", got "${current.phase}"`);
+      }
+    },
+  };
+}

package/dist/_chunks/als-registry-B7DbZ2hS.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"als-registry-B7DbZ2hS.js","names":[],"sources":["../../src/server/als-registry.ts"],"sourcesContent":["/**\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';\n\n// ─── Request Context ──────────────────────────────────────────────────────\n// Used by: request-context.ts (headers(), cookies(), searchParams())\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   * Promise resolving to the route's typed search params (when search-params.ts\n   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework\n   * can later support partial pre-rendering where param resolution is deferred.\n   */\n  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;\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\n/** A single outgoing cookie entry in the cookie jar. */\nexport interface CookieEntry {\n  name: string;\n  value: string;\n  options: import('./request-context.js').CookieOptions;\n}\n\n// ─── Tracing ──────────────────────────────────────────────────────────────\n// Used by: tracing.ts (traceId(), spanId())\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,oBAAoB,IAAI,mBAAwC;;AA4C7E,IAAa,WAAW,IAAI,mBAA+B;;AAW3D,IAAa,YAAY,IAAI,mBAAgC;;AAc7D,IAAa,kBAAkB,IAAI,mBAAsC;;AAOzE,IAAa,eAAe,IAAI,mBAA4D;;AAU5F,IAAa,sBAAsB,IAAI,mBAAuC;;AAU9E,IAAa,eAAe,IAAI,mBAAgC"}