@timber-js/app 0.2.0-alpha.36 → 0.2.0-alpha.37

package/src/server/request-context.ts

@@ -178,6 +178,72 @@ export function rawSearchParams(): Promise<URLSearchParams> {
   return store.searchParamsPromise;
 }
 
+/**
+ * Returns a Promise resolving to the current request's coerced segment params.
+ *
+ * Segment params are set by the pipeline after route matching and param
+ * coercion (via params.ts codecs). When no params.ts exists, values are
+ * raw strings. When codecs are defined, values are already coerced
+ * (e.g., `id` is a `number` if `defineSegmentParams({ id: z.coerce.number() })`).
+ *
+ * This is the primary way page and layout components access route params:
+ *
+ * ```ts
+ * import { rawSegmentParams } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const { slug } = await rawSegmentParams()
+ *   // ...
+ * }
+ * ```
+ *
+ * Throws if called outside a request context.
+ */
+export function rawSegmentParams(): Promise<Record<string, string | string[]>> {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error(
+      '[timber] rawSegmentParams() 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. ' +
+        'Segment params are not available until after the route is matched.'
+    );
+  }
+  return store.segmentParamsPromise;
+}
+
+/**
+ * Set the segment params promise on the current request context.
+ * Called by the pipeline after route matching and param coercion.
+ *
+ * @internal — framework use only
+ */
+export function setSegmentParams(params: Record<string, string | string[]>): void {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error('[timber] setSegmentParams() called outside of a request context.');
+  }
+  store.segmentParamsPromise = Promise.resolve(params);
+}
+
+/**
+ * Returns the raw search string from the current request URL (e.g. "?foo=bar").
+ * Synchronous — safe for use in `redirect()` which throws synchronously.
+ *
+ * Returns empty string if called outside a request context (non-throwing for
+ * use in redirect's optional preserveSearchParams path).
+ *
+ * @internal — used by redirect() for preserveSearchParams support.
+ */
+export function getRequestSearchString(): string {
+  const store = requestContextAls.getStore();
+  return store?.searchString ?? '';
+}
+
 // ─── Types ────────────────────────────────────────────────────────────────
 
 /**
@@ -253,11 +319,13 @@ export interface RequestCookies {
  */
 export function runWithRequestContext<T>(req: Request, fn: () => T): T {
   const originalCopy = new Headers(req.headers);
+  const parsedUrl = new URL(req.url);
   const store: RequestContextStore = {
     headers: freezeHeaders(req.headers),
     originalHeaders: originalCopy,
     cookieHeader: req.headers.get('cookie') ?? '',
-    searchParamsPromise: Promise.resolve(new URL(req.url).searchParams),
+    searchParamsPromise: Promise.resolve(parsedUrl.searchParams),
+    searchString: parsedUrl.search,
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,

package/src/server/route-element-builder.ts

@@ -110,7 +110,7 @@ function rejectLegacyGenerateMetadata(mod: Record<string, unknown>, filePath: st
         `  // Before\n` +
         `  export async function generateMetadata({ params }) { ... }\n\n` +
         `  // After\n` +
-        `  export async function metadata({ params }) { ... }`
+        `  export async function metadata() { ... }`
     );
   }
 }
@@ -119,19 +119,21 @@ function rejectLegacyGenerateMetadata(mod: Record<string, unknown>, filePath: st
  * Extract and resolve metadata from a module (layout or page).
  * Handles both static metadata objects and async metadata functions.
  * Returns the resolved Metadata, or null if none exported.
+ *
+ * Metadata functions no longer receive { params } — they access params
+ * via rawSegmentParams() from ALS, same as page/layout components.
  */
 async function extractMetadata(
   mod: Record<string, unknown>,
-  segment: ManifestSegmentNode,
-  paramsPromise: Promise<Record<string, string | string[]>>
+  segment: ManifestSegmentNode
 ): Promise<Metadata | null> {
   if (typeof mod.metadata === 'function') {
-    type MetadataFn = (props: Record<string, unknown>) => Promise<Metadata>;
+    type MetadataFn = () => Promise<Metadata>;
     return (
       (await withSpan(
         'timber.metadata',
         { 'timber.segment': segment.segmentName ?? segment.urlPath },
-        () => (mod.metadata as MetadataFn)({ params: paramsPromise })
+        () => (mod.metadata as MetadataFn)()
       )) ?? null
     );
   }
@@ -172,9 +174,6 @@ export async function buildRouteElement(
 ): Promise<RouteElementResult> {
   const segments = match.segments as unknown as ManifestSegmentNode[];
 
-  // Params are passed as a Promise to match Next.js 15+ convention.
-  const paramsPromise = Promise.resolve(match.params);
-
   // Load all modules along the segment chain
   const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];
   const layoutComponents: LayoutComponentEntry[] = [];
@@ -199,7 +198,7 @@ export async function buildRouteElement(
       // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
 
       rejectLegacyGenerateMetadata(mod, segment.layout.filePath ?? segment.urlPath);
-      const layoutMetadata = await extractMetadata(mod, segment, paramsPromise);
+      const layoutMetadata = await extractMetadata(mod, segment);
       if (layoutMetadata) {
         metadataEntries.push({ metadata: layoutMetadata, isPage: false });
       }
@@ -217,7 +216,7 @@ export async function buildRouteElement(
         PageComponent = mod.default as (...args: unknown[]) => unknown;
       }
       rejectLegacyGenerateMetadata(mod, segment.page.filePath ?? segment.urlPath);
-      const pageMetadata = await extractMetadata(mod, segment, paramsPromise);
+      const pageMetadata = await extractMetadata(mod, segment);
       if (pageMetadata) {
         metadataEntries.push({ metadata: pageMetadata, isPage: true });
       }
@@ -317,9 +316,7 @@ export async function buildRouteElement(
     );
   };
 
-  let element = h(TracedPage, {
-    params: paramsPromise,
-  });
+  let element = h(TracedPage, {});
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
@@ -399,7 +396,6 @@ export async function buildRouteElement(
       if (accessFn) {
         element = h(AccessGate, {
           accessFn,
-          params: match.params,
           segmentName: segment.segmentName,
           verdict: accessVerdicts.get(i),
           children: element,
@@ -416,7 +412,6 @@ export async function buildRouteElement(
         slotProps[slotName] = await resolveSlotElement(
           slotNode as ManifestSegmentNode,
           match,
-          paramsPromise,
           h,
           interception
         );
@@ -447,7 +442,6 @@ export async function buildRouteElement(
         parallelRouteKeys,
         children: h(TracedLayout, {
           ...slotProps,
-          params: paramsPromise,
           children: element,
         }),
       });

package/src/server/slot-resolver.ts

@@ -45,13 +45,12 @@ async function loadComponent(loader: {
  */
 async function renderDefaultFallback(
   slotNode: ManifestSegmentNode,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement | null> {
   if (!slotNode.default) return null;
   const DefaultComp = await loadComponent(slotNode.default);
   if (!DefaultComp) return null;
-  return h(DefaultComp, { params: paramsPromise });
+  return h(DefaultComp, {});
 }
 
 // ─── Segment Tree Matching ──────────────────────────────────────────────────
@@ -153,7 +152,6 @@ function walkSegmentTree(
 export async function resolveSlotElement(
   slotNode: ManifestSegmentNode,
   match: RouteMatch,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn,
   interception?: InterceptionContext
 ): Promise<React.ReactElement | null> {
@@ -174,7 +172,7 @@ export async function resolveSlotElement(
       // degrade to default.tsx or null — not crash the page. This matches
       // Next.js behavior. See design/02-rendering-pipeline.md
       // §"Slot Access Failure = Graceful Degradation"
-      const denyFallback = await renderDefaultFallback(slotNode, paramsPromise, h);
+      const denyFallback = await renderDefaultFallback(slotNode, h);
 
       // Wrap the slot page to catch DenySignal (from notFound() or deny())
       // at the component level. This prevents the signal from reaching the
@@ -192,23 +190,21 @@ export async function resolveSlotElement(
         }
       };
 
-      let element: React.ReactElement = h(SafeSlotPage, {
-        params: paramsPromise,
-      });
+      let element: React.ReactElement = h(SafeSlotPage, {});
 
       // Wrap with error boundaries and layouts from intermediate slot segments
       // (everything between slot root and leaf). Process innermost-first, same
       // order as route-element-builder.ts handles main segments. The slot root
       // (index 0) is handled separately after the access gate below.
-      element = await wrapWithIntermediateSegments(slotMatch.chain, element, paramsPromise, h);
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h);
 
       // Wrap in SlotAccessGate if slot root has access.ts.
       // On denial: denied.tsx → default.tsx → null (graceful degradation).
       // See design/04-authorization.md §"Slot-Level Auth".
-      element = await wrapWithAccessGate(slotNode, element, paramsPromise, h);
+      element = await wrapWithAccessGate(slotNode, element, h);
 
       // Wrap with slot root's layout (outermost, outside access gate)
-      element = await wrapWithLayout(slotNode, element, paramsPromise, h);
+      element = await wrapWithLayout(slotNode, element, h);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -231,7 +227,7 @@ export async function resolveSlotElement(
   }
 
   // No matching page — render default.tsx fallback
-  return renderDefaultFallback(slotNode, paramsPromise, h);
+  return renderDefaultFallback(slotNode, h);
 }
 
 // ─── Element Wrapping Helpers ───────────────────────────────────────────────
@@ -244,13 +240,12 @@ export async function resolveSlotElement(
 async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement> {
   for (let i = chain.length - 1; i > 0; i--) {
     const seg = chain[i];
     element = await wrapSegmentWithErrorBoundaries(seg, element, h);
-    element = await wrapWithLayout(seg, element, paramsPromise, h);
+    element = await wrapWithLayout(seg, element, h);
   }
   return element;
 }
@@ -261,13 +256,12 @@ async function wrapWithIntermediateSegments(
 async function wrapWithLayout(
   node: ManifestSegmentNode,
   element: React.ReactElement,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement> {
   if (!node.layout) return element;
   const Layout = await loadComponent(node.layout);
   if (!Layout) return element;
-  return h(Layout, { params: paramsPromise, children: element });
+  return h(Layout, { children: element });
 }
 
 /**
@@ -277,7 +271,6 @@ async function wrapWithLayout(
 async function wrapWithAccessGate(
   slotNode: ManifestSegmentNode,
   element: React.ReactElement,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn
 ): Promise<React.ReactElement> {
   if (!slotNode.access) return element;
@@ -295,12 +288,10 @@ async function wrapWithAccessGate(
   // Extract slot name from the directory name (strip @ prefix)
   const slotName = slotNode.segmentName?.replace(/^@/, '') ?? '';
 
-  const defaultFallback = await renderDefaultFallback(slotNode, paramsPromise, h);
-  const params = await paramsPromise;
+  const defaultFallback = await renderDefaultFallback(slotNode, h);
 
   return h(SlotAccessGate, {
     accessFn,
-    params,
     DeniedComponent,
     slotName,
     createElement: h,

package/src/server/tree-builder.ts

@@ -46,8 +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[]>;
+  /**
+   * 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. */
@@ -76,7 +81,6 @@ export interface TreeBuilderConfig {
  */
 export interface AccessGateProps {
   accessFn: (ctx: { params: Record<string, string | string[]> }) => unknown;
-  params: Record<string, string | string[]>;
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
@@ -102,7 +106,6 @@ export interface AccessGateProps {
  */
 export interface SlotAccessGateProps {
   accessFn: (ctx: { params: Record<string, string | string[]> }) => unknown;
-  params: Record<string, string | string[]>;
   /** 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"). */
@@ -149,7 +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, loadModule, createElement, errorBoundaryComponent } = config;
+  const { segments, loadModule, createElement, errorBoundaryComponent } = config;
 
   if (segments.length === 0) {
     throw new Error('[timber] buildElementTree: empty segment chain');
@@ -173,8 +176,8 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     );
   }
 
-  // Build the page element with params prop
-  let element: ReactElement = createElement(PageComponent, { params });
+  // 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--) {
@@ -195,7 +198,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
       const accessFn = accessModule.default as AccessGateProps['accessFn'];
       element = createElement('timber:access-gate', {
         accessFn,
-        params,
         segmentName: segment.segmentName,
         children: element,
       } satisfies AccessGateProps);
@@ -215,7 +217,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
           for (const [slotName, slotNode] of segment.slots) {
             slotProps[slotName] = await buildSlotElement(
               slotNode,
-              params,
               loadModule,
               createElement,
               errorBoundaryComponent
@@ -225,7 +226,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
 
         element = createElement(LayoutComponent, {
           ...slotProps,
-          params,
           children: element,
         });
       }
@@ -245,7 +245,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
  */
 async function buildSlotElement(
   slotNode: SegmentNode,
-  params: Record<string, string | string[]>,
   loadModule: ModuleLoader,
   createElement: CreateElement,
   errorBoundaryComponent: unknown
@@ -262,10 +261,10 @@ async function buildSlotElement(
 
   // If no page, render default.tsx or null
   if (!PageComponent) {
-    return DefaultComponent ? createElement(DefaultComponent, { params }) : null;
+    return DefaultComponent ? createElement(DefaultComponent, {}) : null;
   }
 
-  let element: ReactElement = createElement(PageComponent, { params });
+  let element: ReactElement = createElement(PageComponent, {});
 
   // Wrap in error boundaries
   element = await wrapWithErrorBoundaries(
@@ -287,11 +286,10 @@ async function buildSlotElement(
     const DeniedComponent =
       (deniedModule?.default as ((...args: unknown[]) => ReactElement) | undefined) ?? null;
 
-    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, { params }) : null;
+    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
 
     element = createElement('timber:slot-access-gate', {
       accessFn,
-      params,
       DeniedComponent,
       slotName: slotNode.segmentName.replace(/^@/, ''),
       createElement,

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/dist/_chunks/request-context-CZz_T0Bc.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"request-context-CZz_T0Bc.js","names":[],"sources":["../../src/server/request-context.ts"],"sourcesContent":["/**\n * Request Context — per-request ALS store for headers() and cookies().\n *\n * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage\n * instance, public accessor functions that throw outside request scope,\n * and a framework-internal `runWithRequestContext()` to establish scope.\n *\n * See design/04-authorization.md §\"AccessContext does not include cookies or headers\"\n * and design/11-platform.md §\"AsyncLocalStorage\".\n * See design/29-cookies.md for cookie mutation semantics.\n */\n\nimport { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';\nimport { isDebug } from './debug.js';\n\n// Re-export the ALS for framework-internal consumers that need direct access.\nexport { requestContextAls };\n\n// No fallback needed — we use enterWith() instead of run() to ensure\n// the ALS context persists for the entire request lifecycle including\n// async stream consumption by React's renderToReadableStream.\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns a read-only view of the current request's headers.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n */\nexport function headers(): ReadonlyHeaders {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] headers() 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.headers;\n}\n\n/**\n * Returns a cookie accessor for the current request.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n *\n * Read methods (.get, .has, .getAll) are always available and reflect\n * read-your-own-writes from .set() calls in the same request.\n *\n * Mutation methods (.set, .delete, .clear) are only available in mutable\n * contexts (middleware.ts, server actions, route.ts handlers). Calling them\n * in read-only contexts (access.ts, server components) throws.\n *\n * See design/29-cookies.md\n */\nexport function cookies(): RequestCookies {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] cookies() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n\n  // Parse cookies lazily on first access\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  const map = store.parsedCookies;\n  return {\n    get(name: string): string | undefined {\n      return map.get(name);\n    },\n    has(name: string): boolean {\n      return map.has(name);\n    },\n    getAll(): Array<{ name: string; value: string }> {\n      return Array.from(map.entries()).map(([name, value]) => ({ name, value }));\n    },\n    get size(): number {\n      return map.size;\n    },\n\n    set(name: string, value: string, options?: CookieOptions): void {\n      assertMutable(store, 'set');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: cookies().set('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };\n      store.cookieJar.set(name, { name, value, options: opts });\n      // Read-your-own-writes: update the parsed cookies map\n      map.set(name, value);\n    },\n\n    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {\n      assertMutable(store, 'delete');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: cookies().delete('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts: CookieOptions = {\n        ...DEFAULT_COOKIE_OPTIONS,\n        ...options,\n        maxAge: 0,\n        expires: new Date(0),\n      };\n      store.cookieJar.set(name, { name, value: '', options: opts });\n      // Remove from read view\n      map.delete(name);\n    },\n\n    clear(): void {\n      assertMutable(store, 'clear');\n      if (store.flushed) return;\n      // Delete every incoming cookie\n      for (const name of Array.from(map.keys())) {\n        store.cookieJar.set(name, {\n          name,\n          value: '',\n          options: { ...DEFAULT_COOKIE_OPTIONS, maxAge: 0, expires: new Date(0) },\n        });\n      }\n      map.clear();\n    },\n\n    toString(): string {\n      return Array.from(map.entries())\n        .map(([name, value]) => `${name}=${value}`)\n        .join('; ');\n    },\n  };\n}\n\n/**\n * Returns a Promise resolving to the current request's raw URLSearchParams.\n *\n * For typed, parsed search params, import the definition from params.ts\n * and call `.load()` or `.parse()`:\n *\n * ```ts\n * import { searchParams } from './params'\n * const parsed = await searchParams.load()\n * ```\n *\n * Or explicitly:\n *\n * ```ts\n * import { rawSearchParams } from '@timber-js/app/server'\n * import { searchParams } from './params'\n * const parsed = searchParams.parse(await rawSearchParams())\n * ```\n *\n * Throws if called outside a request context.\n */\nexport function rawSearchParams(): Promise<URLSearchParams> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] rawSearchParams() 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.searchParamsPromise;\n}\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Read-only Headers interface. The standard Headers class is mutable;\n * this type narrows it to read-only methods. The underlying object is\n * still a Headers instance, but user code should not mutate it.\n */\nexport type ReadonlyHeaders = Pick<\n  Headers,\n  'get' | 'has' | 'entries' | 'keys' | 'values' | 'forEach' | typeof Symbol.iterator\n>;\n\n/** Options for setting a cookie. See design/29-cookies.md. */\nexport interface CookieOptions {\n  /** Domain scope. Default: omitted (current domain only). */\n  domain?: string;\n  /** URL path scope. Default: '/'. */\n  path?: string;\n  /** Expiration date. Mutually exclusive with maxAge. */\n  expires?: Date;\n  /** Max age in seconds. Mutually exclusive with expires. */\n  maxAge?: number;\n  /** Prevent client-side JS access. Default: true. */\n  httpOnly?: boolean;\n  /** Only send over HTTPS. Default: true. */\n  secure?: boolean;\n  /** Cross-site request policy. Default: 'lax'. */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */\n  partitioned?: boolean;\n}\n\nconst DEFAULT_COOKIE_OPTIONS: CookieOptions = {\n  path: '/',\n  httpOnly: true,\n  secure: true,\n  sameSite: 'lax',\n};\n\n/**\n * Cookie accessor returned by `cookies()`.\n *\n * Read methods are always available. Mutation methods throw in read-only\n * contexts (access.ts, server components).\n */\nexport interface RequestCookies {\n  /** Get a cookie value by name. Returns undefined if not present. */\n  get(name: string): string | undefined;\n  /** Check if a cookie exists. */\n  has(name: string): boolean;\n  /** Get all cookies as an array of { name, value } pairs. */\n  getAll(): Array<{ name: string; value: string }>;\n  /** Number of cookies. */\n  readonly size: number;\n  /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */\n  set(name: string, value: string, options?: CookieOptions): void;\n  /** Delete a cookie. Only available in mutable contexts. */\n  delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;\n  /** Delete all cookies. Only available in mutable contexts. */\n  clear(): void;\n  /** Serialize cookies as a Cookie header string. */\n  toString(): string;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Run a callback within a request context. Used by the pipeline to establish\n * per-request ALS scope so that `headers()` and `cookies()` work.\n *\n * @param req - The incoming Request object.\n * @param fn - The function to run within the request context.\n */\nexport function runWithRequestContext<T>(req: Request, fn: () => T): T {\n  const originalCopy = new Headers(req.headers);\n  const store: RequestContextStore = {\n    headers: freezeHeaders(req.headers),\n    originalHeaders: originalCopy,\n    cookieHeader: req.headers.get('cookie') ?? '',\n    searchParamsPromise: Promise.resolve(new URL(req.url).searchParams),\n    cookieJar: new Map(),\n    flushed: false,\n    mutableContext: false,\n  };\n  return requestContextAls.run(store, fn);\n}\n\n/**\n * Enable cookie mutation for the current context. Called by the framework\n * when entering middleware.ts, server actions, or route.ts handlers.\n *\n * See design/29-cookies.md §\"Context Tracking\"\n */\nexport function setMutableCookieContext(mutable: boolean): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.mutableContext = mutable;\n  }\n}\n\n/**\n * Mark the response as flushed (headers committed). After this point,\n * cookie mutations log a warning instead of throwing.\n *\n * See design/29-cookies.md §\"Streaming Constraint: Post-Flush Cookie Warning\"\n */\nexport function markResponseFlushed(): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.flushed = true;\n  }\n}\n\n/**\n * Build a Map of cookie name → value reflecting the current request's\n * read-your-own-writes state. Includes incoming cookies plus any\n * mutations from cookies().set() / cookies().delete() in the same request.\n *\n * Used by SSR renderers to populate NavContext.cookies so that\n * useCookie()'s server snapshot matches the actual response state.\n *\n * See design/29-cookies.md §\"Read-Your-Own-Writes\"\n * See design/triage/TIM-441-cookie-api-triage.md §4\n */\nexport function getCookiesForSsr(): Map<string, string> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');\n  }\n\n  // Trigger lazy parsing if not yet done\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  // The parsedCookies map already reflects read-your-own-writes:\n  // - cookies().set() updates the map via map.set(name, value)\n  // - cookies().delete() removes from the map via map.delete(name)\n  // Return a copy so callers can't mutate the internal map.\n  return new Map(store.parsedCookies);\n}\n\n/**\n * Collect all Set-Cookie headers from the cookie jar.\n * Called by the framework at flush time to apply cookies to the response.\n *\n * Returns an array of serialized Set-Cookie header values.\n */\nexport function getSetCookieHeaders(): string[] {\n  const store = requestContextAls.getStore();\n  if (!store) return [];\n  return Array.from(store.cookieJar.values()).map(serializeCookieEntry);\n}\n\n/**\n * Apply middleware-injected request headers to the current request context.\n *\n * Called by the pipeline after middleware.ts runs. Merges overlay headers\n * on top of the original request headers so downstream code (access.ts,\n * server components, server actions) sees them via `headers()`.\n *\n * The original request headers are never mutated — a new frozen Headers\n * object is created with the overlay applied on top.\n *\n * See design/07-routing.md §\"Request Header Injection\"\n */\nexport function applyRequestHeaderOverlay(overlay: Headers): void {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] applyRequestHeaderOverlay() called outside of a request context.');\n  }\n\n  // Check if the overlay has any headers — skip if empty\n  let hasOverlay = false;\n  overlay.forEach(() => {\n    hasOverlay = true;\n  });\n  if (!hasOverlay) return;\n\n  // Merge: start with original headers, overlay on top\n  const merged = new Headers(store.originalHeaders);\n  overlay.forEach((value, key) => {\n    merged.set(key, value);\n  });\n  store.headers = freezeHeaders(merged);\n}\n\n// ─── Read-Only Headers ────────────────────────────────────────────────────\n\nconst MUTATING_METHODS = new Set(['set', 'append', 'delete']);\n\n/**\n * Wrap a Headers object in a Proxy that throws on mutating methods.\n * Object.freeze doesn't work on Headers (native internal slots), so we\n * intercept property access and reject set/append/delete at runtime.\n *\n * Read methods (get, has, entries, etc.) must be bound to the underlying\n * Headers instance because they access private #headersList slots.\n */\nfunction freezeHeaders(source: Headers): Headers {\n  const copy = new Headers(source);\n  return new Proxy(copy, {\n    get(target, prop) {\n      if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {\n        return () => {\n          throw new Error(\n            `[timber] headers() returns a read-only Headers object. ` +\n              `Calling .${prop}() is not allowed. ` +\n              `Use ctx.requestHeaders in middleware to inject headers for downstream components.`\n          );\n        };\n      }\n      const value = Reflect.get(target, prop);\n      // Bind methods to the real Headers instance so private slot access works\n      if (typeof value === 'function') {\n        return value.bind(target);\n      }\n      return value;\n    },\n  });\n}\n\n// ─── Cookie Helpers ───────────────────────────────────────────────────────\n\n/** Throw if cookie mutation is attempted in a read-only context. */\nfunction assertMutable(store: RequestContextStore, method: string): void {\n  if (!store.mutableContext) {\n    throw new Error(\n      `[timber] cookies().${method}() cannot be called in this context.\\n` +\n        `  Set cookies in middleware.ts, server actions, or route.ts handlers.`\n    );\n  }\n}\n\n/**\n * Parse a Cookie header string into a Map of name → value pairs.\n * Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.\n */\nfunction parseCookieHeader(header: string): Map<string, string> {\n  const map = new Map<string, string>();\n  if (!header) return map;\n\n  for (const pair of header.split(';')) {\n    const eqIndex = pair.indexOf('=');\n    if (eqIndex === -1) continue;\n    const name = pair.slice(0, eqIndex).trim();\n    const value = pair.slice(eqIndex + 1).trim();\n    if (name) {\n      map.set(name, value);\n    }\n  }\n\n  return map;\n}\n\n/** Serialize a CookieEntry into a Set-Cookie header value. */\nfunction serializeCookieEntry(entry: CookieEntry): string {\n  const parts = [`${entry.name}=${entry.value}`];\n  const opts = entry.options;\n\n  if (opts.domain) parts.push(`Domain=${opts.domain}`);\n  if (opts.path) parts.push(`Path=${opts.path}`);\n  if (opts.expires) parts.push(`Expires=${opts.expires.toUTCString()}`);\n  if (opts.maxAge !== undefined) parts.push(`Max-Age=${opts.maxAge}`);\n  if (opts.httpOnly) parts.push('HttpOnly');\n  if (opts.secure) parts.push('Secure');\n  if (opts.sameSite) {\n    parts.push(`SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`);\n  }\n  if (opts.partitioned) parts.push('Partitioned');\n\n  return parts.join('; ');\n}\n"],"mappings":"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"}

package/dist/_chunks/segment-context-Dpq2XOKg.js

@@ -1,34 +0,0 @@
-import { createContext, createElement, useContext, useMemo } from "react";
-//#region src/client/segment-context.ts
-/**
-* Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.
-*
-* Each layout in the segment tree is wrapped with a SegmentProvider that stores
-* the URL segments from root to the current layout level. The hooks read this
-* context to determine which child segments are active below the calling layout.
-*
-* The context value is intentionally minimal: just the segment path array and
-* parallel route keys. No internal cache details are exposed.
-*
-* Design docs: design/19-client-navigation.md, design/14-ecosystem.md
-*/
-var SegmentContext = createContext(null);
-/** Read the segment context. Returns null if no provider is above this component. */
-function useSegmentContext() {
-	return useContext(SegmentContext);
-}
-/**
-* Wraps each layout to provide segment position context.
-* Injected by rsc-entry.ts during element tree construction.
-*/
-function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }) {
-	const value = useMemo(() => ({
-		segments,
-		parallelRouteKeys
-	}), [segments.join("/"), parallelRouteKeys.join(",")]);
-	return createElement(SegmentContext.Provider, { value }, children);
-}
-//#endregion
-export { useSegmentContext as n, SegmentProvider as t };
-
-//# sourceMappingURL=segment-context-Dpq2XOKg.js.map

package/dist/_chunks/segment-context-Dpq2XOKg.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"segment-context-Dpq2XOKg.js","names":[],"sources":["../../src/client/segment-context.ts"],"sourcesContent":["/**\n * Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.\n *\n * Each layout in the segment tree is wrapped with a SegmentProvider that stores\n * the URL segments from root to the current layout level. The hooks read this\n * context to determine which child segments are active below the calling layout.\n *\n * The context value is intentionally minimal: just the segment path array and\n * parallel route keys. No internal cache details are exposed.\n *\n * Design docs: design/19-client-navigation.md, design/14-ecosystem.md\n */\n\n'use client';\n\nimport { createContext, useContext, createElement, useMemo } from 'react';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface SegmentContextValue {\n  /** URL segments from root to this layout (e.g. ['', 'dashboard', 'settings']) */\n  segments: string[];\n  /** Parallel route slot keys available at this layout level (e.g. ['sidebar', 'modal']) */\n  parallelRouteKeys: string[];\n}\n\n// ─── Context ─────────────────────────────────────────────────────\n\nconst SegmentContext = createContext<SegmentContextValue | null>(null);\n\n/** Read the segment context. Returns null if no provider is above this component. */\nexport function useSegmentContext(): SegmentContextValue | null {\n  return useContext(SegmentContext);\n}\n\n// ─── Provider ────────────────────────────────────────────────────\n\ninterface SegmentProviderProps {\n  segments: string[];\n  /**\n   * Unique identifier for this segment, used by the client-side segment\n   * merger for element caching. For route groups this includes the group\n   * name (e.g., \"/(marketing)\") since groups share their parent's urlPath.\n   * Falls back to the reconstructed path from `segments` if not provided.\n   */\n  segmentId?: string;\n  parallelRouteKeys: string[];\n  children: React.ReactNode;\n}\n\n/**\n * Wraps each layout to provide segment position context.\n * Injected by rsc-entry.ts during element tree construction.\n */\nexport function SegmentProvider({\n  segments,\n  segmentId: _segmentId,\n  parallelRouteKeys,\n  children,\n}: SegmentProviderProps) {\n  const value = useMemo(\n    () => ({ segments, parallelRouteKeys }),\n    // segments and parallelRouteKeys are static per layout — they don't change\n    // across navigations. The layout's position in the tree is fixed.\n    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout\n    [segments.join('/'), parallelRouteKeys.join(',')]\n  );\n  return createElement(SegmentContext.Provider, { value }, children);\n}\n"],"mappings":";;;;;;;;;;;;;;AA4BA,IAAM,iBAAiB,cAA0C,KAAK;;AAGtE,SAAgB,oBAAgD;AAC9D,QAAO,WAAW,eAAe;;;;;;AAsBnC,SAAgB,gBAAgB,EAC9B,UACA,WAAW,YACX,mBACA,YACuB;CACvB,MAAM,QAAQ,eACL;EAAE;EAAU;EAAmB,GAItC,CAAC,SAAS,KAAK,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC,CAClD;AACD,QAAO,cAAc,eAAe,UAAU,EAAE,OAAO,EAAE,SAAS"}