@timber-js/app 0.2.0-alpha.71 → 0.2.0-alpha.72

package/src/server/internal.ts

@@ -0,0 +1,169 @@
+// #server-internal — Framework-internal server exports
+//
+// This module is a Node package import (#server-internal in package.json
+// "imports" field). It is only resolvable from within @timber-js/app —
+// external consumers cannot import it.
+//
+// These exports are consumed by entry modules (rsc-entry, ssr-entry),
+// adapters, dev server plugins, and build plugins. They are NOT part of
+// the user-facing API and should not appear in documentation or autocomplete
+// for application developers.
+//
+// Design doc: design/triage/api-naming-spike.md §8.5
+
+// ── Request Context internals ────────────────────────────────────────────
+export {
+  setSegmentParams,
+  runWithRequestContext,
+  setMutableCookieContext,
+  markResponseFlushed,
+  getSetCookieHeaders,
+} from './request-context.js';
+
+// ── Signal classes (instanceof targets for pipeline catch logic) ──────────
+export { DenySignal, RedirectSignal, RenderError } from './primitives.js';
+export type { RenderErrorDigest } from './primitives.js';
+
+// ── Pipeline ─────────────────────────────────────────────────────────────
+export { createPipeline } from './pipeline.js';
+export type {
+  PipelineConfig,
+  RouteMatch,
+  RouteMatcher,
+  RouteRenderer,
+  EarlyHintsEmitter,
+} from './pipeline.js';
+
+// ── Early Hints ──────────────────────────────────────────────────────────
+export { collectEarlyHintHeaders, formatLinkHeader } from './early-hints.js';
+export type { EarlyHint } from './early-hints.js';
+
+// ── Early Hints 103 Sender — ALS bridge for platform adapters ────────────
+export { runWithEarlyHintsSender, sendEarlyHints103 } from './early-hints-sender.js';
+export type { EarlyHintsSenderFn } from './early-hints-sender.js';
+
+// ── Canonicalization ─────────────────────────────────────────────────────
+export { canonicalize } from './canonicalize.js';
+export type { CanonicalizeResult } from './canonicalize.js';
+
+// ── Proxy ────────────────────────────────────────────────────────────────
+export { runProxy } from './proxy.js';
+export type { ProxyFn, ProxyExport } from './proxy.js';
+
+// ── Middleware ────────────────────────────────────────────────────────────
+export { runMiddleware } from './middleware-runner.js';
+export type { MiddlewareFn } from './middleware-runner.js';
+
+// ── Tree Builder ─────────────────────────────────────────────────────────
+export { buildElementTree } from './tree-builder.js';
+export type {
+  TreeBuilderConfig,
+  TreeBuildResult,
+  LoadedModule,
+  ModuleLoader,
+  AccessGateProps,
+  SlotAccessGateProps,
+  ErrorBoundaryProps,
+} from './tree-builder.js';
+
+// ── Access Gates ─────────────────────────────────────────────────────────
+export { AccessGate, SlotAccessGate } from './access-gate.js';
+
+// ── Status-Code Resolver ─────────────────────────────────────────────────
+export { resolveStatusFile, resolveSlotDenied } from './status-code-resolver.js';
+export type {
+  StatusFileResolution,
+  StatusFileKind,
+  StatusFileFormat,
+  SlotDeniedResolution,
+  SlotDeniedKind,
+} from './status-code-resolver.js';
+
+// ── Flush Controller ─────────────────────────────────────────────────────
+export { flushResponse } from './flush.js';
+export type { FlushOptions, FlushResult, RenderFn, RenderResult } from './flush.js';
+
+// ── CSRF Protection ──────────────────────────────────────────────────────
+export { validateCsrf } from './csrf.js';
+export type { CsrfConfig, CsrfResult } from './csrf.js';
+
+// ── Body Limits ──────────────────────────────────────────────────────────
+export { parseBodySize, enforceBodyLimits, DEFAULT_LIMITS } from './body-limits.js';
+export type { BodyLimitsConfig, BodyLimitResult, BodyKind } from './body-limits.js';
+
+// ── Metadata ─────────────────────────────────────────────────────────────
+export {
+  resolveMetadata,
+  resolveTitle,
+  resolveMetadataUrls,
+  renderMetadataToElements,
+} from './metadata.js';
+export type { SegmentMetadataEntry, ResolveMetadataOptions, HeadElement } from './metadata.js';
+
+// ── Metadata Routes ──────────────────────────────────────────────────────
+export {
+  classifyMetadataRoute,
+  getMetadataRouteServePath,
+  getMetadataRouteAutoLink,
+  METADATA_ROUTE_CONVENTIONS,
+} from './metadata-routes.js';
+export type { MetadataRouteInfo, MetadataRouteType } from './metadata-routes.js';
+
+// ── Server Actions (pipeline internals) ──────────────────────────────────
+export { executeAction, buildNoJsResponse, isRscActionRequest } from './actions.js';
+export type {
+  RevalidateRenderer,
+  RevalidationState,
+  ActionHandlerConfig,
+  ActionHandlerResult,
+} from './actions.js';
+
+// ── Tracing internals ────────────────────────────────────────────────────
+export { runWithTraceId, replaceTraceId, generateTraceId } from './tracing.js';
+export type { TraceStore } from './tracing.js';
+
+// ── Logger ───────────────────────────────────────────────────────────────
+export { setLogger, getLogger } from './logger.js';
+export {
+  logRequestCompleted,
+  logRequestReceived,
+  logSlowRequest,
+  logMiddlewareShortCircuit,
+  logMiddlewareError,
+  logRenderError,
+  logProxyError,
+  logWaitUntilUnsupported,
+  logWaitUntilRejected,
+  logSwrRefetchFailed,
+  logCacheMiss,
+} from './logger.js';
+export type { TimberLogger } from './logger.js';
+
+// ── Instrumentation ──────────────────────────────────────────────────────
+export { loadInstrumentation, callOnRequestError, hasOnRequestError } from './instrumentation.js';
+export type {
+  InstrumentationOnRequestError,
+  InstrumentationRequestInfo,
+  InstrumentationErrorContext,
+} from './instrumentation.js';
+
+// ── Dev Warnings ─────────────────────────────────────────────────────────
+export {
+  warnSuspenseWrappingChildren,
+  warnDenyInSuspense,
+  warnRedirectInSuspense,
+  warnRedirectInAccess,
+  warnStaticRequestApi,
+  warnSlowSlotWithoutSuspense,
+  setViteServer,
+  WarningId,
+} from './dev-warnings.js';
+export type { DevWarningConfig } from './dev-warnings.js';
+
+// ── Route Handler ────────────────────────────────────────────────────────
+export { handleRouteRequest, resolveAllowedMethods } from './route-handler.js';
+export type { RouteModule, RouteHandler, HttpMethod } from './route-handler.js';
+
+// ── Render Timeout ───────────────────────────────────────────────────────
+export { RenderTimeoutError } from './render-timeout.js';
+export type { RenderTimeout } from './render-timeout.js';

package/src/server/pipeline.ts

@@ -30,7 +30,7 @@ import {
   replaceTraceId,
   withSpan,
   setSpanAttribute,
-  traceId,
+  getTraceId,
 } from './tracing.js';
 import {
   logRequestReceived,
@@ -245,7 +245,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     const traceIdValue = generateTraceId();
 
     return runWithTraceId(traceIdValue, async () => {
-      // Establish request context ALS scope so headers() and cookies() work
+      // Establish request context ALS scope so getHeaders() and getCookies() work
       // throughout the entire request lifecycle (proxy, middleware, render).
       return runWithRequestContext(req, async () => {
         // In dev mode, wrap with timing collector for Server-Timing header.
@@ -533,7 +533,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     }
 
     // Store coerced segment params in ALS so components can access them
-    // via rawSegmentParams() instead of receiving them as a prop.
+    // via getSegmentParams() instead of receiving them as a prop.
     // See design/07-routing.md §"params.ts — Convention File for Typed Params"
     setSegmentParams(match.segmentParams);
 
@@ -578,16 +578,21 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           applyCookieJar(finalResponse.headers);
           // Merge parent-set responseHeaders onto the short-circuit response.
           // Child-set headers take precedence — only add headers not already present.
+          // Snapshot existing keys first so multi-value headers (Set-Cookie, Link)
+          // from the parent are all appended when the child didn't set that key.
+          const existingKeys = new Set(
+            [...finalResponse.headers.keys()].map((k) => k.toLowerCase())
+          );
           for (const [key, value] of responseHeaders.entries()) {
-            if (!finalResponse.headers.has(key)) {
-              finalResponse.headers.set(key, value);
+            if (!existingKeys.has(key.toLowerCase())) {
+              finalResponse.headers.append(key, value);
             }
           }
           logMiddlewareShortCircuit({ method, path, status: finalResponse.status });
           return finalResponse;
         }
         // Middleware chain completed without short-circuiting — apply any
-        // injected request headers so headers() returns them downstream.
+        // injected request headers so getHeaders() returns them downstream.
         applyRequestHeaderOverlay(requestHeaderOverlay);
       } catch (error) {
         setMutableCookieContext(false);
@@ -669,7 +674,7 @@ async function fireOnRequestError(
   await callOnRequestError(
     error,
     { method: req.method, path: url.pathname, headers: headersObj },
-    { phase, routePath: url.pathname, routeType: 'page', traceId: traceId() }
+    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
   );
 }
 

package/src/server/primitives.ts

@@ -145,37 +145,65 @@ export class DenySignal extends Error {
   }
 }
 
+/** Options for deny() when using the object form. */
+export interface DenyOptions {
+  /** HTTP status code (4xx or 5xx). Default: 403. */
+  status?: number;
+  /** Human-readable message (logged server-side, not sent to client). */
+  message?: string;
+  /** JSON-serializable data passed as `dangerouslyPassData` prop to status-code files. */
+  data?: JsonSerializable;
+}
+
 /**
- * Universal denial primitive. Throws a `DenySignal` that the framework catches.
+ * Universal denial/error primitive. Throws a `DenySignal` that the framework catches.
  *
  * - In segment context (outside Suspense): produces HTTP status code
  * - In slot context: graceful degradation → denied.tsx → default.tsx → null
  * - Inside Suspense (hold window): promoted to pre-flush behavior
  * - Inside Suspense (after flush): error boundary + noindex meta
  *
- * @param status - Any 4xx HTTP status code. Defaults to 403.
- * @param data - Optional JSON-serializable data passed as `dangerouslyPassData` prop to status-code files.
+ * Supports both positional and object signatures:
+ * ```ts
+ * deny()                                          // 403 (default)
+ * deny(404)                                       // 404
+ * deny(503, { retry: true })                      // 503 with data
+ * deny({ status: 503, message: 'Maintenance' })   // object form
+ * ```
+ *
+ * Accepts any 4xx or 5xx status code. This replaces the need for
+ * `throw new RenderError(...)` in user code — RenderError is now an
+ * internal pipeline detail.
+ *
+ * @param statusOrOptions - Status code (number) or options object. Default: 403.
+ * @param data - Optional JSON-serializable data (positional form only).
  */
-export function deny(status: number = 403, data?: JsonSerializable): never {
-  if (status < 400 || status > 499) {
-    throw new Error(
-      `deny() requires a 4xx status code, got ${status}. ` +
-        'For 5xx errors, throw a RenderError instead.'
-    );
+export function deny(statusOrOptions?: number | DenyOptions, data?: JsonSerializable): never {
+  let status: number;
+  let resolvedData: JsonSerializable | undefined;
+
+  if (typeof statusOrOptions === 'object' && statusOrOptions !== null) {
+    status = statusOrOptions.status ?? 403;
+    resolvedData = statusOrOptions.data;
+  } else {
+    status = statusOrOptions ?? 403;
+    resolvedData = data;
+  }
+
+  if (status < 400 || status > 599) {
+    throw new Error(`deny() requires a 4xx or 5xx status code, got ${status}.`);
   }
-  warnIfNotSerializable(data, 'deny()');
-  throw new DenySignal(status, data);
+  warnIfNotSerializable(resolvedData, 'deny()');
+  throw new DenySignal(status, resolvedData);
 }
 
 /**
- * Convenience alias for `deny(404)`.
- *
- * Provided for Next.js API compatibility — libraries and user code that
- * call `notFound()` from `next/navigation` get the same behavior as
- * `deny(404)` in timber.
+ * @deprecated Use `deny(404)` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
 export function notFound(): never {
-  throw new DenySignal(404);
+  deny(404);
 }
 
 /**
@@ -215,8 +243,17 @@ const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
  * Options for redirect() — alternative to passing a bare status code.
  */
 export interface RedirectOptions {
-  /** HTTP redirect status code (3xx). Defaults to 302. */
+  /** HTTP redirect status code (3xx). Defaults to 302 (or 308 when `permanent: true`). */
   status?: number;
+  /**
+   * When true, defaults the status to 308 (Permanent Redirect, preserves HTTP method).
+   * If `status` is also provided, `status` takes precedence.
+   *
+   * @example
+   * redirect('/new-path', { permanent: true });       // 308
+   * redirect('/new-path', { permanent: true, status: 301 }); // 301
+   */
+  permanent?: boolean;
   /**
    * Preserve search params from the current request URL on the redirect target.
    *
@@ -246,10 +283,18 @@ export interface RedirectOptions {
  * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
  */
 export function redirect(path: string, statusOrOptions?: number | RedirectOptions): never {
-  const status =
-    typeof statusOrOptions === 'number' ? statusOrOptions : (statusOrOptions?.status ?? 302);
-  const preserveSearchParams =
-    typeof statusOrOptions === 'object' ? statusOrOptions.preserveSearchParams : undefined;
+  let status: number;
+  let preserveSearchParams: true | string[] | undefined;
+
+  if (typeof statusOrOptions === 'number') {
+    status = statusOrOptions;
+  } else if (statusOrOptions) {
+    // Explicit status wins. Otherwise permanent: true → 308, default → 302.
+    status = statusOrOptions.status ?? (statusOrOptions.permanent ? 308 : 302);
+    preserveSearchParams = statusOrOptions.preserveSearchParams;
+  } else {
+    status = 302;
+  }
 
   if (status < 300 || status > 399) {
     throw new Error(`redirect() requires a 3xx status code, got ${status}.`);
@@ -271,16 +316,12 @@ export function redirect(path: string, statusOrOptions?: number | RedirectOption
 }
 
 /**
- * Permanent redirect to a relative path. Shorthand for `redirect(path, 308)`.
- *
- * Uses 308 (Permanent Redirect) which preserves the HTTP method — the browser
- * will replay POST requests to the new location. This matches Next.js behavior.
- *
- * @param path - Relative path (e.g. '/new-page', '/dashboard')
- * @param options - Optional redirect options (e.g. preserveSearchParams).
+ * @deprecated Use `redirect(path, { permanent: true })` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
 export function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never {
-  redirect(path, { status: 308, ...options });
+  redirect(path, { permanent: true, ...options });
 }
 
 /**

package/src/server/request-context.ts

@@ -1,5 +1,5 @@
 /**
- * Request Context — per-request ALS store for headers() and cookies().
+ * Request Context — per-request ALS store for getHeaders() and getCookies().
  *
  * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage
  * instance, public accessor functions that throw outside request scope,
@@ -12,8 +12,8 @@
 
 import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
 import { isDebug } from './debug.js';
-import { _setRawSearchParamsFn } from '../search-params/define.js';
-import { _setRawSegmentParamsFn } from '../segment-params/define.js';
+import { _setGetSearchParamsFn } from '../search-params/define.js';
+import { _setGetSegmentParamsFn } from '../segment-params/define.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -30,15 +30,34 @@ export { requestContextAls };
  * Available in middleware, access checks, server components, and server actions.
  * Throws if called outside a request context (security principle #2: no global fallback).
  */
-export function headers(): ReadonlyHeaders {
+export function getHeaders(): Promise<ReadonlyHeaders> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] headers() called outside of a request context. ' +
+      '[timber] getHeaders() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  return store.headers;
+  return Promise.resolve(store.headers);
+}
+
+/**
+ * Returns the value of a single request header, or undefined if absent.
+ *
+ * Thin wrapper over `(await getHeaders()).get(name)` for the common
+ * case where you need exactly one header.
+ *
+ * ```ts
+ * import { getHeader } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const auth = await getHeader('authorization');
+ * }
+ * ```
+ */
+export async function getHeader(name: string): Promise<string | undefined> {
+  const headers = await getHeaders();
+  return headers.get(name) ?? undefined;
 }
 
 /**
@@ -56,11 +75,11 @@ export function headers(): ReadonlyHeaders {
  *
  * See design/29-cookies.md
  */
-export function cookies(): RequestCookies {
+export function getCookies(): Promise<RequestCookies> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] cookies() called outside of a request context. ' +
+      '[timber] getCookies() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
@@ -71,7 +90,7 @@ export function cookies(): RequestCookies {
   }
 
   const map = store.parsedCookies;
-  return {
+  return Promise.resolve({
     get(name: string): string | undefined {
       return map.get(name);
     },
@@ -90,7 +109,7 @@ export function cookies(): RequestCookies {
       if (store.flushed) {
         if (isDebug()) {
           console.warn(
-            `[timber] warn: cookies().set('${name}') called after response headers were committed.\n` +
+            `[timber] warn: getCookies().set('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
               `  or a route.ts handler.`
           );
@@ -107,7 +126,7 @@ export function cookies(): RequestCookies {
       assertMutable(store, 'setFromHeaders');
       if (store.flushed) {
         console.warn(
-          `[timber] warn: cookies().setFromHeaders() called after response headers were committed.\n` +
+          `[timber] warn: getCookies().setFromHeaders() called after response headers were committed.\n` +
             `  The cookies will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
             `  or a route.ts handler.`
         );
@@ -131,7 +150,7 @@ export function cookies(): RequestCookies {
       if (store.flushed) {
         if (isDebug()) {
           console.warn(
-            `[timber] warn: cookies().delete('${name}') called after response headers were committed.\n` +
+            `[timber] warn: getCookies().delete('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\n` +
               `  or a route.ts handler.`
           );
@@ -168,7 +187,26 @@ export function cookies(): RequestCookies {
         .map(([name, value]) => `${name}=${value}`)
         .join('; ');
     },
-  };
+  });
+}
+
+/**
+ * Returns the value of a single cookie, or undefined if absent.
+ *
+ * Thin wrapper over `(await getCookies()).get(name)` for the common
+ * case where you need exactly one cookie.
+ *
+ * ```ts
+ * import { getCookie } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const session = await getCookie('session_id');
+ * }
+ * ```
+ */
+export async function getCookie(name: string): Promise<string | undefined> {
+  const cookies = await getCookies();
+  return cookies.get(name);
 }
 
 /**
@@ -179,40 +217,40 @@ export function cookies(): RequestCookies {
  *
  * ```ts
  * import { searchParams } from './params'
- * const parsed = await searchParams.load()
+ * const parsed = await searchParams.get()
  * ```
  *
  * Or explicitly:
  *
  * ```ts
- * import { rawSearchParams } from '@timber-js/app/server'
+ * import { getSearchParams } from '@timber-js/app/server'
  * import { searchParams } from './params'
- * const parsed = searchParams.parse(await rawSearchParams())
+ * const parsed = searchParams.parse(await getSearchParams())
  * ```
  *
  * Throws if called outside a request context.
  */
-export function rawSearchParams(): Promise<URLSearchParams> {
+export function getSearchParams(): Promise<URLSearchParams> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] rawSearchParams() called outside of a request context. ' +
+      '[timber] getSearchParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
   return store.searchParamsPromise;
 }
 
-// Eagerly register rawSearchParams with the search-params module so
-// searchParams.load() can call it synchronously without a dynamic import.
+// Eagerly register getSearchParams with the search-params module so
+// searchParams.get() can call it synchronously without a dynamic import.
 // Dynamic imports lose ALS context in React's RSC Flight renderer,
-// breaking rawSearchParams() in parallel slot pages. See TIM-523.
-_setRawSearchParamsFn(rawSearchParams);
+// breaking getSearchParams() in parallel slot pages. See TIM-523.
+_setGetSearchParamsFn(getSearchParams);
 
-// Eagerly register rawSegmentParams with the segment-params module so
-// segmentParams.load() can call it synchronously without a dynamic import.
+// Eagerly register getSegmentParams with the segment-params module so
+// segmentParams.get() can call it synchronously without a dynamic import.
 // Same pattern as search params — dynamic imports lose ALS context. See TIM-523.
-_setRawSegmentParamsFn(rawSegmentParams);
+_setGetSegmentParamsFn(getSegmentParams);
 
 /**
  * Returns a Promise resolving to the current request's coerced segment params.
@@ -225,27 +263,27 @@ _setRawSegmentParamsFn(rawSegmentParams);
  * This is the primary way page and layout components access route params:
  *
  * ```ts
- * import { rawSegmentParams } from '@timber-js/app/server'
+ * import { getSegmentParams } from '@timber-js/app/server'
  *
  * export default async function Page() {
- *   const { slug } = await rawSegmentParams()
+ *   const { slug } = await getSegmentParams()
  *   // ...
  * }
  * ```
  *
  * Throws if called outside a request context.
  */
-export function rawSegmentParams(): Promise<Record<string, string | string[]>> {
+export function getSegmentParams(): Promise<Record<string, string | string[]>> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] rawSegmentParams() called outside of a request context. ' +
+      '[timber] getSegmentParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
   if (!store.segmentParamsPromise) {
     throw new Error(
-      '[timber] rawSegmentParams() called before route matching completed. ' +
+      '[timber] getSegmentParams() called before route matching completed. ' +
         'Segment params are not available until after the route is matched.'
     );
   }
@@ -402,7 +440,7 @@ function parseSetCookie(
 }
 
 /**
- * Cookie accessor returned by `cookies()`.
+ * Cookie accessor returned by `getCookies()`.
  *
  * Read methods are always available. Mutation methods throw in read-only
  * contexts (access.ts, server components).
@@ -426,7 +464,7 @@ export interface RequestCookies {
    * Useful when forwarding cookies from an internal `fetch()` or auth handler:
    * ```ts
    * const response = await auth.handler(req);
-   * cookies().setFromHeaders(response.headers);
+   * getCookies().then(c => c.setFromHeaders(response.headers));
    * ```
    */
   setFromHeaders(headers: Headers): void;
@@ -442,7 +480,7 @@ export interface RequestCookies {
 
 /**
  * Run a callback within a request context. Used by the pipeline to establish
- * per-request ALS scope so that `headers()` and `cookies()` work.
+ * per-request ALS scope so that `getHeaders()` and `getCookies()` work.
  *
  * @param req - The incoming Request object.
  * @param fn - The function to run within the request context.
@@ -492,7 +530,7 @@ export function markResponseFlushed(): void {
 /**
  * Build a Map of cookie name → value reflecting the current request's
  * read-your-own-writes state. Includes incoming cookies plus any
- * mutations from cookies().set() / cookies().delete() in the same request.
+ * mutations from getCookies().set() / getCookies().delete() in the same request.
  *
  * Used by SSR renderers to populate NavContext.cookies so that
  * useCookie()'s server snapshot matches the actual response state.
@@ -512,8 +550,8 @@ export function getCookiesForSsr(): Map<string, string> {
   }
 
   // The parsedCookies map already reflects read-your-own-writes:
-  // - cookies().set() updates the map via map.set(name, value)
-  // - cookies().delete() removes from the map via map.delete(name)
+  // - getCookies().set() updates the map via map.set(name, value)
+  // - getCookies().delete() removes from the map via map.delete(name)
   // Return a copy so callers can't mutate the internal map.
   return new Map(store.parsedCookies);
 }
@@ -535,7 +573,7 @@ export function getSetCookieHeaders(): string[] {
  *
  * Called by the pipeline after middleware.ts runs. Merges overlay headers
  * on top of the original request headers so downstream code (access.ts,
- * server components, server actions) sees them via `headers()`.
+ * server components, server actions) sees them via `getHeaders()`.
  *
  * The original request headers are never mutated — a new frozen Headers
  * object is created with the overlay applied on top.
@@ -582,7 +620,7 @@ function freezeHeaders(source: Headers): Headers {
       if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {
         return () => {
           throw new Error(
-            `[timber] headers() returns a read-only Headers object. ` +
+            `[timber] getHeaders() returns a read-only Headers object. ` +
               `Calling .${prop}() is not allowed. ` +
               `Use ctx.requestHeaders in middleware to inject headers for downstream components.`
           );
@@ -604,7 +642,7 @@ function freezeHeaders(source: Headers): Headers {
 function assertMutable(store: RequestContextStore, method: string): void {
   if (!store.mutableContext) {
     throw new Error(
-      `[timber] cookies().${method}() cannot be called in this context.\n` +
+      `(timber] getCookies().${method}() cannot be called in this context.\n` +
         `  Set cookies in middleware.ts, server actions, or route.ts handlers.`
     );
   }