@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/shared/status-reason-phrase.ts

@@ -0,0 +1,61 @@
+/**
+ * Reason phrases for the framework default status page.
+ *
+ * Shared between the server-rendered default page (`server/default-status-page.ts`,
+ * the HTML terminal of the deny chain) and its client-rendered counterpart
+ * (`client/deny-last-resort.tsx`, the terminal a streamed deny reaches when no
+ * status file sits at or above the component that denied). One table, so the
+ * two surfaces cannot drift — a reader who sees "403 Forbidden" on a document
+ * load must see the same words after a client navigation.
+ *
+ * Nothing here is caller-supplied text: the phrase is looked up from a clamped
+ * integer, never interpolated from a request. See design/13-security.md
+ * principle 4 ("Errors don't leak").
+ */
+
+/**
+ * Canonical reason phrases (RFC 9110 §15) for the statuses an app is likely to
+ * `deny()` with. Anything else falls back to a generic category phrase.
+ */
+const REASON_PHRASES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  413: 'Content Too Large',
+  415: 'Unsupported Media Type',
+  418: "I'm a Teapot",
+  422: 'Unprocessable Content',
+  429: 'Too Many Requests',
+  451: 'Unavailable For Legal Reasons',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+};
+
+/**
+ * Coerce a status into something safe to put in markup.
+ *
+ * `DenySignal.status` is typed `number` but nothing validates it at
+ * construction, and JS callers can hand us anything. Rather than escaping a
+ * value that should never have been a string, collapse non-integers to 500 —
+ * the page is decoration for a status already on the wire.
+ */
+export function displayStatus(status: number): number {
+  return Number.isInteger(status) && status >= 100 && status <= 599 ? status : 500;
+}
+
+/** Human-readable phrase for a status code. Never caller-supplied text. */
+export function statusReasonPhrase(status: number): string {
+  const code = displayStatus(status);
+  if (REASON_PHRASES[code]) return REASON_PHRASES[code];
+  return code >= 500 ? 'Server Error' : 'Request Error';
+}

package/src/shims/font-google.ts

@@ -17,7 +17,7 @@
  * Design doc: 24-fonts.md, "Next.js Font Compatibility"
  */
 
-import type { GoogleFontConfig, FontResult } from '#/fonts/types.js';
+import type { GoogleFontConfig, FontResult } from '../fonts/types.ts';
 
 export type { GoogleFontConfig, FontResult };
 

package/src/shims/font-local.ts

@@ -0,0 +1,34 @@
+/**
+ * Fallback shim for `next/font/local` → `@timber/fonts/local`.
+ *
+ * At build time, the timber-fonts plugin's transform hook replaces
+ * `localFont()` calls with static FontResult objects containing real
+ * class names and font stacks. This file serves two purposes:
+ *
+ * 1. **TypeScript resolution** — provides types for IDEs and `tsc` outside
+ *    of Vite's module graph (where the virtual module handles it).
+ * 2. **Runtime fallback** — returns empty className/fontFamily values when
+ *    the plugin hasn't processed a call (e.g. in tests or non-Vite environments).
+ *
+ * Design doc: 24-fonts.md, "Next.js Font Compatibility"
+ */
+
+import type { LocalFontConfig, FontResult } from '../fonts/types.ts';
+
+export type { LocalFontConfig, FontResult };
+
+/**
+ * Create a local font.
+ *
+ * The timber-fonts plugin replaces these calls at build time with real
+ * class names and font stacks. This stub ensures code that imports
+ * `localFont` outside of the build pipeline (tests, type-checking)
+ * gets a valid FontResult shape without runtime errors.
+ */
+export default function localFont(config?: LocalFontConfig): FontResult {
+  return {
+    className: '',
+    style: { fontFamily: '' },
+    variable: config?.variable,
+  };
+}

package/src/shims/headers.ts

@@ -4,6 +4,127 @@
  * Imports from @timber-js/app/server which Vite resolves to dist/server/index.js
  * via native package.json exports. This ensures the same ALS singleton as the
  * pipeline (both import from the same shared request-context chunk in dist/).
+ *
+ * `cookies()` is NOT a bare alias of `getCookieJar()`: Next.js's
+ * RequestCookies returns `{ name, value }` RequestCookie objects from
+ * `.get()`/`.getAll()`, while timber's native jar returns bare strings from
+ * `.get()`. Ecosystem libraries written against the real API use
+ * `(await cookies()).get('session')?.value` — with the bare-string shape
+ * that silently reads `undefined` off a string. The adapter below presents
+ * the Next shape while delegating every operation to the timber jar, so the
+ * encoding contract, cookie-octet validation, and mutable-context checks
+ * (design/29-cookies.md, ONGOING_SECURITY.md H-3) apply unchanged.
+ * See TIM-1042 and design/14-ecosystem.md §next/headers.
+ */
+
+import { getCookieJar } from '@timber-js/app/server';
+import type { CookieOptions, SetCookieOptions } from '@timber-js/app/server';
+
+// Re-export timber's primary API
+export { getHeaders, getCookieJar } from '@timber-js/app/server';
+
+// Next.js compat alias — libraries importing from 'next/headers' expect this name.
+export { getHeaders as headers } from '@timber-js/app/server';
+
+/** Next.js's request cookie shape: `cookies().get(name)` → `{ name, value }`. */
+export interface RequestCookie {
+  name: string;
+  value: string;
+}
+
+/** Next.js's `cookies().set()` options — `expires` may be a ms timestamp. */
+export interface NextCookieOptions extends Omit<SetCookieOptions, 'expires'> {
+  expires?: Date | number;
+}
+
+/** Next.js's object overload for `cookies().set({ name, value, ...options })`. */
+export interface NextCookieListItem extends NextCookieOptions {
+  name: string;
+  value: string;
+}
+
+/** Next.js's RequestCookies surface, backed by timber's cookie jar. */
+export interface NextRequestCookies {
+  get(name: string): RequestCookie | undefined;
+  get(cookie: RequestCookie): RequestCookie | undefined;
+  getAll(name?: string): RequestCookie[];
+  getAll(cookie: RequestCookie): RequestCookie[];
+  has(name: string): boolean;
+  readonly size: number;
+  set(name: string, value: string, options?: NextCookieOptions): void;
+  set(cookie: NextCookieListItem): void;
+  delete(name: string): void;
+  delete(cookie: { name: string } & Pick<CookieOptions, 'path' | 'domain'>): void;
+  [Symbol.iterator](): IterableIterator<[string, RequestCookie]>;
+  toString(): string;
+}
+
+/** Normalize Next's `expires?: Date | number` (ms timestamp) to timber's `Date`. */
+function normalizeOptions(options?: NextCookieOptions): SetCookieOptions | undefined {
+  if (!options) return undefined;
+  const { expires, ...rest } = options;
+  if (typeof expires === 'number') return { ...rest, expires: new Date(expires) };
+  return options as SetCookieOptions;
+}
+
+/**
+ * Next.js compat: `cookies()` returning the RequestCookies shape.
+ *
+ * Next.js 15 makes `cookies()` async; awaiting this sync return value works
+ * for both the `(await cookies()).get()` and legacy `cookies().get()` call
+ * styles, so libraries targeting either Next version resolve correctly.
  */
+export function cookies(): NextRequestCookies {
+  const jar = getCookieJar();
+
+  const toCookie = (name: string): RequestCookie | undefined => {
+    const value = jar.get(name);
+    return value === undefined ? undefined : { name, value };
+  };
 
-export { headers, cookies } from '@timber-js/app/server';
+  return {
+    get(nameOrCookie: string | RequestCookie): RequestCookie | undefined {
+      return toCookie(typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name);
+    },
+    getAll(nameOrCookie?: string | RequestCookie): RequestCookie[] {
+      const all = jar.getAll();
+      if (nameOrCookie === undefined) return all;
+      const name = typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name;
+      return all.filter((cookie) => cookie.name === name);
+    },
+    has(name: string): boolean {
+      return jar.has(name);
+    },
+    get size(): number {
+      return jar.size;
+    },
+    set(
+      nameOrCookie: string | NextCookieListItem,
+      value?: string,
+      options?: NextCookieOptions
+    ): void {
+      if (typeof nameOrCookie === 'string') {
+        jar.set(nameOrCookie, value as string, normalizeOptions(options));
+      } else {
+        const { name, value: cookieValue, ...objectOptions } = nameOrCookie;
+        jar.set(name, cookieValue, normalizeOptions(objectOptions));
+      }
+    },
+    delete(nameOrCookie: string | ({ name: string } & Pick<CookieOptions, 'path' | 'domain'>)) {
+      if (typeof nameOrCookie === 'string') {
+        jar.delete(nameOrCookie);
+      } else {
+        const { name, ...options } = nameOrCookie;
+        jar.delete(name, options);
+      }
+    },
+    *[Symbol.iterator](): IterableIterator<[string, RequestCookie]> {
+      for (const cookie of jar.getAll()) {
+        yield [cookie.name, cookie];
+      }
+    },
+    toString(): string {
+      return jar.toString();
+    },
+  };
+}

package/src/shims/navigation-client.ts

@@ -1,12 +1,19 @@
 /**
  * Shim: next/navigation (client environment only)
  *
- * Re-exports only the client-side hooks from timber's client API.
- * Server-only functions (redirect, notFound, etc.) are excluded to prevent
- * server/primitives.ts from being pulled into the browser bundle.
+ * Re-exports the client-side hooks from timber's client API, and implements
+ * client-render `redirect()` without pulling server/primitives.ts into the
+ * browser bundle.
+ *
+ * Next.js supports calling redirect() during client component render.
+ * timber matches that by throwing a plain Error carrying the same JSON
+ * digest the server pipeline attaches to RedirectSignal. TimberErrorBoundary
+ * recognizes the digest and converts it to an SPA navigation (replace
+ * semantics), and browser-dev's isFrameworkSignalError() keeps it out of
+ * the dev overlay.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
- * where both client hooks and server functions are needed.
+ * where the real server primitives produce proper HTTP responses.
  *
  * Imports use @timber-js/app/client (not #/ subpath imports) so they resolve
  * to the same module instances as user code in Vite dev — preventing module
@@ -16,42 +23,39 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks — imported from the public barrel for module singleton consistency.
+import { assertRelativeRedirectPath } from '../shared/href-validation.ts';
+import type { RedirectTypeValue } from '../shared/redirect-type.ts';
+
+// Hooks — useSegmentParams and useSearchParams import from direct modules
+// since they're no longer in @timber-js/app/client public exports.
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.ts';
+export { useSearchParams } from '../client/use-search-params.ts';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
-// RedirectType enum is safe (no server code dependency) and used by some
-// client-side libraries for type checking.
-export const RedirectType = {
-  push: 'push',
-  replace: 'replace',
-} as const;
-
-// Server-only stubs — throw at runtime if called from the client.
-// These exist for type compatibility with libraries that import the types
-// but should never execute in the browser.
-export function redirect(): never {
-  throw new Error(
-    'redirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
-}
+// Single source of truth shared with server/primitives.ts.
+export { RedirectType } from '../shared/redirect-type.ts';
 
-export function permanentRedirect(): never {
-  throw new Error(
-    'permanentRedirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
+/** Throw a plain Error carrying a framework signal digest. */
+function throwSignal(message: string, digest: Record<string, unknown>): never {
+  const err = new Error(message);
+  (err as Error & { digest?: string }).digest = JSON.stringify(digest);
+  throw err;
 }
 
-export function notFound(): never {
-  throw new Error(
-    'notFound() is a server-only function and cannot be called from client components.'
-  );
+/**
+ * Client-render redirect. Throws a redirect-digest error that the nearest
+ * TimberErrorBoundary converts into an SPA navigation (replace semantics).
+ *
+ * The optional RedirectType argument is accepted for Next.js API
+ * compatibility but ignored — timber always uses replace semantics,
+ * matching the server-side redirect().
+ */
+export function redirect(path: string, _type?: RedirectTypeValue): never {
+  assertRelativeRedirectPath(path);
+  throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 302 });
 }

package/src/shims/navigation-rsc.ts

@@ -0,0 +1,47 @@
+/**
+ * Shim: next/navigation → RSC environment only
+ *
+ * RSC's stripped-down React provides neither `useContext` nor `createContext`,
+ * so the real hook modules cannot be evaluated there. This shim exports
+ * throwing stubs for every client hook, with the same error messages the
+ * guards previously produced inline, and re-exports the server functions
+ * from @timber-js/app/server unchanged.
+ *
+ * The shims plugin resolves `next/navigation` to this file in the RSC
+ * environment, `navigation.ts` in SSR, and `navigation-client.ts` in the
+ * browser. This split eliminates the `typeof React.useContext !== 'function'`
+ * guards that React Compiler flagged as conditional hook calls (TIM-1420).
+ */
+
+function clientOnlyHook(name: string, extra?: string): never {
+  throw new Error(
+    `[timber] ${name}() is only available in Client Components. ` +
+      (extra ?? "Add 'use client' to the module that calls it.")
+  );
+}
+
+export function usePathname(): string {
+  clientOnlyHook('usePathname');
+}
+
+export function useSearchParams(): URLSearchParams {
+  clientOnlyHook('useSearchParams');
+}
+
+export function useSegmentParams(): Record<string, unknown> {
+  clientOnlyHook(
+    'useSegmentParams',
+    "In a Server Component, use getSegmentParams() from '@timber-js/app/server'; " +
+      "otherwise add 'use client' to the module that calls it."
+  );
+}
+
+export { useSegmentParams as useParams };
+
+export {
+  useRouter,
+  useSelectedLayoutSegment,
+  useSelectedLayoutSegments,
+} from '@timber-js/app/client';
+
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';

package/src/shims/navigation.ts

@@ -1,20 +1,23 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks import from @timber-js/app/client (the public barrel) so they
- * resolve to the same module instances as user code in Vite dev. Server
- * functions import from @timber-js/app/server for ALS singleton consistency.
+ * Client hooks import from their direct modules since useSegmentParams,
+ * useSearchParams, and useQueryStates are no longer part of
+ * @timber-js/app/client public exports (they live on define* factories).
+ * The shim re-exports them for next/navigation library compat (nuqs etc).
+ *
+ * Server functions import from @timber-js/app/server for ALS singleton consistency.
  */
 
-// Hooks (client-side — imported from public barrel for module singleton)
+// Hooks re-exported for next/navigation compat
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.ts';
+export { useSearchParams } from '../client/use-search-params.ts';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
 // Functions (server-side)
-export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';

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/src/utils/write-file-atomic.ts

@@ -0,0 +1,32 @@
+/**
+ * Replace a file's contents in one step: write a uniquely named temp sibling,
+ * then `rename()` it over the target.
+ *
+ * `writeFile()` opens its target with `O_TRUNC`, so for the length of the write
+ * a concurrent reader sees an empty or half-written file under the real name.
+ * `rename()` within one directory swaps the name atomically, so a reader sees
+ * either the old file or the new one — never a torn one — and a crashed
+ * writer leaves no partial artifact under the final name.
+ *
+ * The temp name is unique per call, not a fixed `${path}.tmp`: two writers of
+ * the same path (a dev server and a `vite build` rewriting the same route
+ * types, parallel CLI invocations sharing a cache) would otherwise write into
+ * one temp file and rename each other's half-written bytes into place.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { rename, rm, writeFile } from 'node:fs/promises';
+
+export async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, data);
+    await rename(tmp, path);
+  } catch (err) {
+    // Best-effort cleanup. If the directory refuses the write it may refuse
+    // the rm too, and that error — naming a random temp path — must not
+    // replace the one that says what actually failed.
+    await rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}

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

@@ -1,41 +0,0 @@
-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),
-* 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
-export { timingAls as a, revalidationAls as i, formFlashAls as n, traceAls as o, requestContextAls as r, waitUntilAls as s, earlyHintsSenderAls as t };
-
-//# sourceMappingURL=als-registry-B7DbZ2hS.js.map

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"}