@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/src/server/als-registry.ts

@@ -21,9 +21,10 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
 // ─── Request Context ──────────────────────────────────────────────────────
-// Used by: request-context.ts (headers(), cookies(), searchParams())
+// Used by: request-context.ts (getHeaders(), getCookies(), getSearchParams())
 // Design doc: design/04-authorization.md
 
 /** @internal — import via request-context.ts public API */
@@ -39,28 +40,55 @@ export interface RequestContextStore {
   /** Original (pre-overlay) frozen headers, kept for overlay merging. */
   originalHeaders: Headers;
   /**
-   * Promise resolving to the route's typed search params (when search-params.ts
-   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-   * can later support partial pre-rendering where param resolution is deferred.
+   * Raw URLSearchParams for the current request.
+   * To get typed parsed params, import a search params definition and
+   * call `.parse(searchParams())`.
    */
-  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+  searchParams: URLSearchParams;
+  /**
+   * Raw search string from the request URL (e.g. "?foo=bar&baz=1").
+   * Available synchronously for use in `redirect()` with `preserveSearchParams`.
+   */
+  searchString: string;
+  /**
+   * Coerced segment params for the current request.
+   * Set by the pipeline after route matching and param coercion, before
+   * middleware and rendering. Pages and layouts read params via
+   * `getSegmentParams()` instead of receiving them as a prop.
+   *
+   * See design/07-routing.md §"params.ts — Convention File for Typed Params"
+   */
+  segmentParams?: Record<string, string | string[]>;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */
   flushed: boolean;
   /** Whether the current context allows cookie mutation. */
   mutableContext: boolean;
+  /**
+   * Set by AccessGate or PageDenyBoundary when a DenySignal is caught
+   * server-side (inside the React tree, before React Flight sees it).
+   * The pipeline reads this after render to set the HTTP status code.
+   * See TIM-666.
+   */
+  denyStatus?: number;
+  /**
+   * Dev-only: getter for the current request's RSC debug components.
+   * Set by renderRoute() so onPipelineError can include component tree
+   * context for render-phase errors without module-level shared state.
+   */
+  debugComponentsGetter?: () => DebugComponentEntry[];
 }
 
 /** A single outgoing cookie entry in the cookie jar. */
 export interface CookieEntry {
   name: string;
   value: string;
-  options: import('./request-context.js').CookieOptions;
+  options: import('./cookie-context.js').CookieOptions;
 }
 
 // ─── Tracing ──────────────────────────────────────────────────────────────
-// Used by: tracing.ts (traceId(), spanId())
+// Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md
 
 export interface TraceStore {

package/src/server/asset-headers.ts

@@ -15,6 +15,14 @@
  * Design docs: 18-build-system.md, 06-caching.md
  */
 
+import { IMMUTABLE_CACHE, STATIC_CACHE } from '../adapters/shared.js';
+
+// Re-export cache constants and generateHeadersFile from the shared adapter
+// module. The canonical definitions live in adapters/shared.ts because
+// adapters are loaded by Node before Vite's resolver is available — they
+// can only import from within their own directory.
+export { IMMUTABLE_CACHE, STATIC_CACHE, generateHeadersFile } from '../adapters/shared.js';
+
 /**
  * Regex matching Vite-hashed asset filenames.
  *
@@ -30,18 +38,6 @@
  */
 const HASHED_ASSET_RE = /[-.][\da-f]{8,}\.\w+$/;
 
-/** One year in seconds (365 days). */
-const ONE_YEAR = 31_536_000;
-
-/** One hour in seconds. */
-const ONE_HOUR = 3_600;
-
-/** Cache-Control value for hashed (immutable) assets. */
-export const IMMUTABLE_CACHE = `public, max-age=${ONE_YEAR}, immutable`;
-
-/** Cache-Control value for unhashed static assets. */
-export const STATIC_CACHE = `public, max-age=${ONE_HOUR}, must-revalidate`;
-
 /**
  * Check if a URL path looks like a hashed asset.
  */
@@ -57,25 +53,3 @@ export function isHashedAsset(pathname: string): boolean {
 export function getAssetCacheControl(pathname: string): string {
   return isHashedAsset(pathname) ? IMMUTABLE_CACHE : STATIC_CACHE;
 }
-
-/**
- * Generate a `_headers` file for static asset cache control.
- *
- * The `_headers` file is a platform convention supported by Cloudflare Workers
- * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
- * HTTP response headers.
- *
- * Vite places all hashed chunks under `/assets/` — these get immutable caching.
- * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
- */
-export function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}

package/src/server/build-manifest.ts

@@ -85,6 +85,12 @@ export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildMan
  * via injectHead() before </head>.
  */
 export function buildCssLinkTags(cssUrls: string[]): string {
+  // Emit <link rel="stylesheet"> tags as a fallback for platforms where
+  // React's Float system (via @vitejs/plugin-rsc preinit with
+  // data-precedence) doesn't handle CSS injection. In practice, Float
+  // deduplicates and these may be dropped. No preload hints — Float
+  // already starts the fetch via preinit(), and redundant preloads
+  // cause "ignored due to unknown as/type" browser warnings.
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 
@@ -95,10 +101,10 @@ export function buildCssLinkTags(cssUrls: string[]): string {
  * into 103 Early Hints responses. This avoids platform-specific 103
  * sending code.
  *
- * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
+ * Example output: `</assets/root.css>; as=style; rel=preload, </assets/page.css>; as=style; rel=preload`
  */
 export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
+  return cssUrls.map((url) => `<${url}>; as=style; rel=preload`).join(', ');
 }
 
 // ─── Font utilities ──────────────────────────────────────────────────────
@@ -153,10 +159,10 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
  *
  * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
  *
- * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
+ * Example: `</fonts/inter.woff2>; as=font; rel=preload; crossorigin`
  */
 export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
+  return fonts.map((f) => `<${f.href}>; as=font; rel=preload; crossorigin`).join(', ');
 }
 
 // ─── JS chunk utilities ──────────────────────────────────────────────────

package/src/server/compress.ts

@@ -160,15 +160,33 @@ export function compressResponse(request: Request, response: Response): Response
   });
 }
 
-// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────
+//
+// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed
+// to the output immediately. The Web Platform CompressionStream API buffers
+// internally and does NOT flush per-chunk — this kills streaming because
+// the browser doesn't receive the HTML shell until the gzip stream closes
+// (i.e. after all Suspense boundaries resolve).
+//
+// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves
+// correct streaming behavior: the shell renders instantly, Suspense
+// fallbacks are visible immediately, and streamed content appears
+// progressively.
+
+import { createGzip, constants } from 'node:zlib';
+import { Readable } from 'node:stream';
 
 /**
- * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
- * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ * Compress a ReadableStream with gzip, flushing each chunk immediately.
+ *
+ * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+ * (shell, Suspense resolution, RSC payload) is delivered to the browser
+ * as soon as it's available — preserving streaming semantics.
  */
 function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const compressionStream = new CompressionStream('gzip');
-  // Cast needed: CompressionStream's WritableStream<BufferSource> type is wider
-  // than ReadableStream's Uint8Array, but Uint8Array is a valid BufferSource.
-  return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
+  nodeInput.pipe(gzip);
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }

package/src/server/cookie-context.ts

@@ -0,0 +1,468 @@
+/**
+ * Cookie Context — per-request cookie API and on-the-wire helpers.
+ *
+ * Split out of `request-context.ts` (TIM-853) so the cookie subsystem
+ * — encoding contract, options grammar, parser, serializer, RYW map,
+ * and rerender seed — lives in one file. The headers/scope/params APIs
+ * stay in `request-context.ts` and call into this module via the
+ * exported helpers.
+ *
+ * See design/29-cookies.md for the encoding contract and read-your-own-
+ * writes semantics. See ONGOING_SECURITY.md H-3 (TIM-868) for the
+ * smuggling primitive that the encoding contract closes.
+ */
+
+import { requestContextAls, type RequestContextStore } from './als-registry.js';
+import { isDebug } from './debug.js';
+import { assertValidCookieName, assertValidCookieValue } from '../cookies/validation.js';
+import {
+  parseCookieHeader,
+  parseSetCookie,
+  safeDecodeCookieValue,
+  serializeCookieEntry,
+} from './cookie-parsing.js';
+
+// Re-export the validators so framework-internal consumers and tests can
+// import the canonical implementation from the same module that hosts
+// `getCookies()`. The pure shared module lives in `cookies/validation.ts`
+// so the client `useCookie` hook can use the same checks without pulling
+// in the server ALS code.
+export { assertValidCookieName, assertValidCookieValue };
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Returns a cookie accessor for the current request.
+ *
+ * Available in middleware, access checks, server components, and server actions.
+ * Throws if called outside a request context (security principle #2: no global fallback).
+ *
+ * Read methods (.get, .has, .getAll) are always available and reflect
+ * read-your-own-writes from .set() calls in the same request.
+ *
+ * Mutation methods (.set, .delete, .clear) are only available in mutable
+ * contexts (middleware.ts, server actions, route.ts handlers). Calling them
+ * in read-only contexts (access.ts, server components) throws.
+ *
+ * This is the escape hatch for direct cookie jar operations. For typed
+ * cookie access, use `defineCookie()` instead.
+ *
+ * See design/29-cookies.md
+ */
+export function getCookieJar(): RequestCookies {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error(
+      '[timber] getCookieJar() called outside of a request context. ' +
+        'It can only be used in middleware, access checks, server components, and server actions.'
+    );
+  }
+
+  // Parse cookies lazily on first access
+  if (!store.parsedCookies) {
+    store.parsedCookies = parseCookieHeader(store.cookieHeader);
+  }
+
+  const map = store.parsedCookies;
+  return {
+    get(name: string): string | undefined {
+      return map.get(name);
+    },
+    has(name: string): boolean {
+      return map.has(name);
+    },
+    getAll(): Array<{ name: string; value: string }> {
+      return Array.from(map.entries()).map(([name, value]) => ({ name, value }));
+    },
+    get size(): number {
+      return map.size;
+    },
+
+    set(name: string, value: string, options?: SetCookieOptions): void {
+      assertMutable(store, 'set');
+      // Validate the name first — names cannot be URL-encoded (RFC 7230
+      // token grammar is strict), so a bad name is always a bug.
+      assertValidCookieName(name);
+      // Type guard with a guiding error. The single most common mistake
+      // is passing a non-string (object, number, Date) and expecting the
+      // framework to JSON-encode. Point developers at jsonCookieCodec.
+      if (typeof value !== 'string') {
+        throw new Error(
+          `[timber] getCookieJar().set(${JSON.stringify(name)}, …): value must be a string, got ${typeof value}.\n` +
+            `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec:\n` +
+            `\n` +
+            `    import { defineCookie, jsonCookieCodec } from '@timber-js/app/cookies';\n` +
+            `\n` +
+            `    export const ${name}Cookie = defineCookie(${JSON.stringify(name)}, {\n` +
+            `      codec: jsonCookieCodec(),\n` +
+            `    });\n` +
+            `\n` +
+            `    ${name}Cookie.set(value);\n` +
+            `\n` +
+            `  See design/29-cookies.md §"Typed Cookies with Schema Validation".`
+        );
+      }
+      // Encode the value so the on-the-wire bytes always satisfy
+      // RFC 6265 §4.1.1 cookie-octet. encodeURIComponent's output is a
+      // strict subset of cookie-octet (only `A-Z a-z 0-9 ! ' ( ) * - . _
+      // ~ %`), so the encoded form can never carry the H-3 smuggling
+      // primitive — `;` becomes `%3B`, CR/LF become `%0D`/`%0A`, etc.
+      // The round-trip is lossless: parseCookieHeader auto-decodes on
+      // read, so `cookies().get(name)` returns exactly `value`. See
+      // ONGOING_SECURITY.md H-3 (TIM-868) and design/29-cookies.md
+      // §"Encoding Contract".
+      //
+      // The `{ raw: true }` opt-out skips the encoder for callers who
+      // need exact byte control (e.g. forwarding pre-encoded cookies
+      // from an upstream service). The opt-out goes through the strict
+      // cookie-octet validator instead — the smuggling primitive cannot
+      // sneak in via the escape hatch.
+      const raw = options?.raw === true;
+      const wireValue = raw ? value : encodeURIComponent(value);
+      if (raw) {
+        assertValidCookieValue(name, wireValue);
+      }
+      if (store.flushed) {
+        if (isDebug()) {
+          console.warn(
+            `[timber] warn: getCookieJar().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.`
+          );
+        }
+        return;
+      }
+      // Strip the framework-only `raw` flag before persisting — it is
+      // not an HTTP cookie attribute and must not leak into the jar.
+      const { raw: _raw, ...attributeOptions } = options ?? {};
+      void _raw;
+      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...attributeOptions };
+      store.cookieJar.set(name, { name, value: wireValue, options: opts });
+      // Read-your-own-writes: store the DECODED logical value so that
+      // subsequent `cookies().get(name)` in the same request returns
+      // exactly what the developer wrote — never the encoded form.
+      // For `{ raw: true }`, the wire form IS the logical form.
+      map.set(name, raw ? wireValue : value);
+    },
+
+    setFromHeaders(headers: Headers): void {
+      assertMutable(store, 'setFromHeaders');
+      if (store.flushed) {
+        console.warn(
+          `[timber] warn: getCookieJar().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.`
+        );
+        return;
+      }
+      // Headers.getSetCookie() returns individual Set-Cookie strings,
+      // avoiding the fragile comma-splitting that raw .get() requires.
+      for (const raw of headers.getSetCookie()) {
+        const parsed = parseSetCookie(raw);
+        if (parsed) {
+          // Use setRaw to preserve the original header's attributes without
+          // merging DEFAULT_COOKIE_OPTIONS (parseSetCookie intentionally
+          // does not apply defaults — see its doc comment).
+          setRaw(store, map, parsed.name, parsed.value, parsed.options);
+        }
+      }
+    },
+
+    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
+      assertMutable(store, 'delete');
+      // Validate the name even though delete writes an empty value — a
+      // smuggled name (`;` or CR/LF) would corrupt the Set-Cookie header
+      // we emit. See ONGOING_SECURITY.md H-3 (TIM-868).
+      assertValidCookieName(name);
+      if (store.flushed) {
+        if (isDebug()) {
+          console.warn(
+            `[timber] warn: getCookieJar().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.`
+          );
+        }
+        return;
+      }
+      const opts: CookieOptions = {
+        ...DEFAULT_COOKIE_OPTIONS,
+        ...options,
+        maxAge: 0,
+        expires: new Date(0),
+      };
+      store.cookieJar.set(name, { name, value: '', options: opts });
+      // Remove from read view
+      map.delete(name);
+    },
+
+    clear(): void {
+      assertMutable(store, 'clear');
+      if (store.flushed) return;
+      // Delete every incoming cookie
+      for (const name of Array.from(map.keys())) {
+        store.cookieJar.set(name, {
+          name,
+          value: '',
+          options: { ...DEFAULT_COOKIE_OPTIONS, maxAge: 0, expires: new Date(0) },
+        });
+      }
+      map.clear();
+    },
+
+    toString(): string {
+      // Re-encode values when serializing as a Cookie header — the
+      // RYW map holds decoded logical values, but a Cookie header has
+      // to satisfy `cookie-octet`. Mirror the auto-encode contract on
+      // `set()` so toString() round-trips losslessly with parseCookieHeader.
+      return Array.from(map.entries())
+        .map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
+        .join('; ');
+    },
+  };
+}
+
+/**
+ * Returns the value of a single cookie, or undefined if absent.
+ *
+ * @internal — not part of the public API. Use `defineCookie().get()` or `getCookieJar().get()` instead.
+ */
+export function getCookie(name: string): string | undefined {
+  const jar = getCookieJar();
+  return jar.get(name);
+}
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/**
+ * Per-call options for `getCookies().set()`. Extends the persistent
+ * `CookieOptions` (HTTP cookie attributes) with framework-only flags
+ * that are NOT serialized into the Set-Cookie header.
+ *
+ * The `raw` flag is the escape hatch for the auto-encoding contract.
+ * See design/29-cookies.md §"Encoding Contract".
+ */
+export interface SetCookieOptions extends CookieOptions {
+  /**
+   * Skip the framework's `encodeURIComponent` pass and store the value
+   * verbatim. The value is then validated against the strict RFC 6265
+   * §4.1.1 `cookie-octet` grammar — the H-3 smuggling primitive cannot
+   * sneak in via this opt-out.
+   *
+   * Use this when forwarding a cookie value that is already in its
+   * intended on-the-wire form (e.g. mirroring an upstream service's
+   * Set-Cookie). Default: `false` (auto-encode).
+   */
+  raw?: boolean;
+}
+
+/** Options for setting a cookie. See design/29-cookies.md. */
+export interface CookieOptions {
+  /** Domain scope. Default: omitted (current domain only). */
+  domain?: string;
+  /** URL path scope. Default: '/'. */
+  path?: string;
+  /** Expiration date. Mutually exclusive with maxAge. */
+  expires?: Date;
+  /** Max age in seconds. Mutually exclusive with expires. */
+  maxAge?: number;
+  /** Prevent client-side JS access. Default: true. */
+  httpOnly?: boolean;
+  /** Only send over HTTPS. Default: true. */
+  secure?: boolean;
+  /** Cross-site request policy. Default: 'lax'. */
+  sameSite?: 'strict' | 'lax' | 'none';
+  /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */
+  partitioned?: boolean;
+}
+
+/**
+ * Cookie accessor returned by `getCookies()`.
+ *
+ * Read methods are always available. Mutation methods throw in read-only
+ * contexts (access.ts, server components).
+ */
+export interface RequestCookies {
+  /** Get a cookie value by name. Returns undefined if not present. */
+  get(name: string): string | undefined;
+  /** Check if a cookie exists. */
+  has(name: string): boolean;
+  /** Get all cookies as an array of { name, value } pairs. */
+  getAll(): Array<{ name: string; value: string }>;
+  /** Number of cookies. */
+  readonly size: number;
+  /**
+   * Set a cookie. Only available in mutable contexts (middleware, actions,
+   * route handlers).
+   *
+   * The value is auto-encoded with `encodeURIComponent` so the on-the-wire
+   * bytes always satisfy RFC 6265 §4.1.1 cookie-octet — `cookies().get()`
+   * returns the same logical value the developer wrote. Pass `{ raw: true }`
+   * to skip the encoder; the raw path validates against the strict
+   * cookie-octet grammar instead. See design/29-cookies.md §"Encoding
+   * Contract" and ONGOING_SECURITY.md H-3 (TIM-868).
+   */
+  set(name: string, value: string, options?: SetCookieOptions): void;
+  /**
+   * Copy all `Set-Cookie` headers from a `Headers` object.
+   * Parses each header and forwards name, value, and all attributes
+   * (path, domain, max-age, expires, sameSite, secure, httpOnly, partitioned).
+   *
+   * Useful when forwarding cookies from an internal `fetch()` or auth handler:
+   * ```ts
+   * const response = await auth.handler(req);
+   * getCookies().then(c => c.setFromHeaders(response.headers));
+   * ```
+   */
+  setFromHeaders(headers: Headers): void;
+  /** Delete a cookie. Only available in mutable contexts. */
+  delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+  /** Delete all cookies. Only available in mutable contexts. */
+  clear(): void;
+  /** Serialize cookies as a Cookie header string. */
+  toString(): string;
+}
+
+const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
+  path: '/',
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',
+};
+
+// ─── Framework-Internal Helpers ───────────────────────────────────────────
+
+/**
+ * Per-request seed map of cookie name → value, registered out-of-band so the
+ * pipeline's `runWithRequestContext` call can pick it up without changing
+ * the function's calling convention. Stored in a WeakMap keyed by the
+ * synthetic Request object built for the rerender path, so the seed lives
+ * exactly as long as the request and is collected with it.
+ *
+ * The seed exists to eliminate the parse/serialize round-trip on the no-JS
+ * form-rerender path — see ONGOING_SECURITY.md H-3 (TIM-868). The action's
+ * post-mutation RYW snapshot is threaded directly into the rerender scope's
+ * `parsedCookies` map, bypassing `parseCookieHeader` entirely.
+ */
+const seededRequestCookies = new WeakMap<Request, Map<string, string>>();
+
+/**
+ * Register a pre-parsed cookie map to use as the request context seed for
+ * the next `runWithRequestContext(req, …)` call with this exact `req`.
+ *
+ * Used by the no-JS form-rerender dispatcher in
+ * `rsc-entry/wrap-action-dispatch.ts` to thread the action's post-mutation
+ * cookie state into the rerender scope without serializing back through a
+ * `Cookie:` header. See TIM-868 / TIM-837.
+ *
+ * @internal — framework use only.
+ */
+export function seedRequestCookies(req: Request, cookies: Map<string, string>): void {
+  // Defensive copy: callers must not be able to mutate the rerender scope's
+  // map after seeding, and the rerender scope must not mutate the snapshot
+  // we hand back to other observers.
+  seededRequestCookies.set(req, new Map(cookies));
+}
+
+/**
+ * Pop the seed (if any) for `req` and return it. Called from
+ * `runWithRequestContext` exactly once per request — the seed is consumed
+ * eagerly so it cannot leak into a hypothetical future re-use of the same
+ * Request reference.
+ *
+ * @internal — framework use only.
+ */
+export function consumeSeededCookies(req: Request): Map<string, string> | undefined {
+  const seed = seededRequestCookies.get(req);
+  if (seed) seededRequestCookies.delete(req);
+  return seed;
+}
+
+/**
+ * Build a Map of cookie name → value reflecting the current request's
+ * read-your-own-writes state. Includes incoming cookies plus any
+ * 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.
+ *
+ * See design/29-cookies.md §"Read-Your-Own-Writes"
+ * See design/triage/TIM-441-cookie-api-triage.md §4
+ */
+export function getCookiesForSsr(): Map<string, string> {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');
+  }
+
+  // Trigger lazy parsing if not yet done
+  if (!store.parsedCookies) {
+    store.parsedCookies = parseCookieHeader(store.cookieHeader);
+  }
+
+  // The parsedCookies map already reflects read-your-own-writes:
+  // - 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);
+}
+
+/**
+ * Collect all Set-Cookie headers from the cookie jar.
+ * Called by the framework at flush time to apply cookies to the response.
+ *
+ * Returns an array of serialized Set-Cookie header values.
+ */
+export function getSetCookieHeaders(): string[] {
+  const store = requestContextAls.getStore();
+  if (!store) return [];
+  return Array.from(store.cookieJar.values()).map(serializeCookieEntry);
+}
+
+// ─── Cookie Helpers ───────────────────────────────────────────────────────
+
+/** Throw if cookie mutation is attempted in a read-only context. */
+function assertMutable(store: RequestContextStore, method: string): void {
+  if (!store.mutableContext) {
+    throw new Error(
+      `[timber] getCookieJar().${method}() cannot be called in this context.\n` +
+        `  Set cookies in middleware.ts, server actions, or route.ts handlers.`
+    );
+  }
+}
+
+/**
+ * Write a cookie to the jar WITHOUT merging DEFAULT_COOKIE_OPTIONS.
+ * Used by setFromHeaders to preserve the original header's attributes exactly.
+ *
+ * For deletion cookies (maxAge=0), the jar entry is still created so the
+ * Set-Cookie header is emitted, but the cookie is NOT added to the read map
+ * (it would be misleading — the cookie is being deleted).
+ */
+function setRaw(
+  store: RequestContextStore,
+  readMap: Map<string, string>,
+  name: string,
+  value: string,
+  options: CookieOptions
+): void {
+  // setRaw is the forwarding path for upstream Set-Cookie headers
+  // (`getCookies().setFromHeaders(response.headers)`). The value comes
+  // out of `parseSetCookie` in its on-the-wire form — already encoded
+  // by whoever produced it — so we re-emit it verbatim into our jar.
+  // We DO validate against the strict cookie-octet grammar, both as
+  // defense-in-depth against a malicious upstream and to keep the
+  // ONGOING_SECURITY.md H-3 invariant intact at every entry point into
+  // the cookie jar / RYW map.
+  assertValidCookieName(name);
+  assertValidCookieValue(name, value);
+  store.cookieJar.set(name, { name, value, options });
+  // Deletion cookies (Max-Age=0) should not appear in the read map.
+  if (options.maxAge === 0) {
+    readMap.delete(name);
+  } else {
+    // Decode for the RYW map so consumers see the same logical bytes
+    // they would see if the upstream cookie had arrived on the next
+    // request. Mirrors `parseCookieHeader`'s auto-decode.
+    readMap.set(name, safeDecodeCookieValue(value));
+  }
+}