@timber-js/app 0.2.0-alpha.17 → 0.2.0-alpha.171

package/dist/server/primitives.d.ts

@@ -21,37 +21,46 @@ export declare class DenySignal extends Error {
      */
     get sourceFile(): string | undefined;
 }
+/** 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.
- */
-export declare function deny(status?: number, data?: JsonSerializable): never;
-/**
- * Convenience alias for `deny(404)`.
+ * 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.
  *
- * 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.
+ * @param statusOrOptions - Status code (number) or options object. Default: 403.
+ * @param data - Optional JSON-serializable data (positional form only).
  */
-export declare function notFound(): never;
+export declare function deny(statusOrOptions?: number | DenyOptions, data?: JsonSerializable): never;
 /**
- * Next.js redirect type discriminator.
- *
- * Provided for API compatibility with libraries that import `RedirectType`
- * from `next/navigation`. In timber, `redirect()` always uses `replace`
- * semantics (no history entry for the redirect itself).
+ * @deprecated Use `deny(404)` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
-export declare const RedirectType: {
-    readonly push: "push";
-    readonly replace: "replace";
-};
+export declare function notFound(): never;
+export { RedirectType } from '../shared/redirect-type.js';
 /**
  * Render-phase signal thrown by `redirect()` and `redirectExternal()`.
  * Caught by the framework to produce a 3xx response or client-side navigation.
@@ -61,28 +70,71 @@ export declare class RedirectSignal extends Error {
     readonly status: number;
     constructor(location: string, status: number);
 }
+/**
+ * Returns true if the error is a framework control-flow signal (RedirectSignal
+ * or DenySignal) rather than a genuine application error. Works both for direct
+ * instances (RSC-side) and deserialized digest errors (SSR cross-boundary).
+ *
+ * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
+ */
+export declare function isControlFlowSignal(error: unknown): boolean;
+/**
+ * Options for redirect() — alternative to passing a bare status code.
+ */
+export interface RedirectOptions {
+    /** 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.
+     *
+     * - `true` — preserve ALL current search params (target params take precedence)
+     * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+     *
+     * Target path's own query params always take precedence over preserved ones.
+     */
+    preserveSearchParams?: true | string[];
+}
 /**
  * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
  * Use `redirectExternal()` for external redirects with an allow-list.
  *
  * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
- * @param status - HTTP redirect status code (3xx). Defaults to 302.
- */
-export declare function redirect(path: string, status?: number): never;
-/**
- * Permanent redirect to a relative path. Shorthand for `redirect(path, 308)`.
+ * @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
  *
- * Uses 308 (Permanent Redirect) which preserves the HTTP method — the browser
- * will replay POST requests to the new location. This matches Next.js behavior.
+ * @example
+ * // Simple redirect
+ * redirect('/login');
  *
- * @param path - Relative path (e.g. '/new-page', '/dashboard')
+ * // With status code
+ * redirect('/login', 301);
+ *
+ * // With preserved search params
+ * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
+ */
+export declare function redirect(path: string, statusOrOptions?: number | RedirectOptions): never;
+/**
+ * @deprecated Use `redirect(path, { permanent: true })` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
-export declare function permanentRedirect(path: string): never;
+export declare function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never;
 /**
- * Redirect to an external URL. The hostname must be in the provided allow-list.
+ * Redirect to an external URL. The origin must be in the provided allow-list.
+ *
+ * Only http: and https: schemes are permitted. The allow-list is matched
+ * against full origins (scheme + host + port), not bare hostnames.
  *
  * @param url - Absolute URL to redirect to.
- * @param allowList - Array of allowed hostnames (e.g. ['example.com', 'auth.example.com']).
+ * @param allowList - Array of allowed origins (e.g. ['https://example.com', 'https://auth.example.com']).
  * @param status - HTTP redirect status code (3xx). Defaults to 302.
  */
 export declare function redirectExternal(url: string, allowList: string[], status?: number): never;
@@ -116,25 +168,18 @@ export declare class RenderError<TCode extends string = string, TData extends Js
         status?: number;
     });
 }
-/** Minimal interface for adapters that support background work. */
-export interface WaitUntilAdapter {
-    waitUntil?(promise: Promise<unknown>): void;
-}
 /**
  * Register a promise to be kept alive after the response is sent.
  * Maps to `ctx.waitUntil()` on Cloudflare Workers and similar platforms.
  *
- * In production, the platform adapter installs a per-request waitUntil
- * function via ALS (see waituntil-bridge.ts). This function checks the
- * ALS bridge first, then falls back to the legacy adapter argument.
- *
- * If neither is available, a warning is logged once and the promise is
- * left to resolve (or reject) without being tracked.
+ * The platform adapter installs a per-request waitUntil function via ALS
+ * (see waituntil-bridge.ts). If no ALS handler is available, a warning
+ * is logged once and the promise is left to resolve (or reject) without
+ * being tracked.
  *
  * @param promise - The background work to keep alive.
- * @param adapter - Optional legacy adapter (prefer ALS bridge in production).
  */
-export declare function waitUntil(promise: Promise<unknown>, adapter?: WaitUntilAdapter): void;
+export declare function waitUntil(promise: Promise<unknown>): void;
 /**
  * Reset the waitUntil warning state. Exported for testing only.
  * @internal

package/dist/server/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/server/primitives.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMnD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAS,GAAG,MAAM,GAAG,IAAI,CA8DhF;AAsBD;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC;gBAEhC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB;IAOnD;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAqBnC;CACF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,MAAM,GAAE,MAAY,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,KAAK,CASzE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAEhC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAIX;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM7C;AAKD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY,GAAG,KAAK,CAWlE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,MAAY,GAAG,KAAK,CAoB9F;AAID;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,KAAK,SAAS,gBAAgB,GAAG,gBAAgB;IAEjD,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW,CACtB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,KAAK,SAAS,gBAAgB,GAAG,gBAAgB,CACjD,SAAQ,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAcpE;AAID,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAqBrF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAID;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,KAAK;aAGrB,KAAK,EAAE,OAAO;gBAD9B,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,OAAO;CAKjC"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/server/primitives.ts"],"names":[],"mappings":"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"}

package/dist/server/render-timeout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Render timeout utilities for SSR streaming pipeline.
+ *
+ * Provides a RenderTimeoutError class and a helper to create
+ * timeout-guarded AbortSignals. Used to defend against hung RSC
+ * streams and infinite SSR renders.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+ */
+/**
+ * Error thrown when an SSR render or RSC stream read exceeds the
+ * configured timeout. Callers can check `instanceof RenderTimeoutError`
+ * to distinguish timeout from other errors and return a 504 or close
+ * the connection cleanly.
+ */
+export declare class RenderTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, context?: string);
+}
+/**
+ * Result of createRenderTimeout — an AbortSignal that fires after
+ * the given duration, plus a cancel function to clear the timer
+ * when the render completes normally.
+ */
+export interface RenderTimeout {
+    /** AbortSignal that aborts after timeoutMs. */
+    signal: AbortSignal;
+    /** Cancel the timeout timer. Call this when the render completes. */
+    cancel: () => void;
+}
+/**
+ * Create a render timeout that aborts after the given duration.
+ *
+ * Returns an AbortSignal and a cancel function. The signal fires
+ * with a RenderTimeoutError as the abort reason after `timeoutMs`.
+ * Call `cancel()` when the render completes to prevent the timeout
+ * from firing.
+ *
+ * If an existing `parentSignal` is provided, the returned signal
+ * aborts when either the parent signal or the timeout fires —
+ * whichever comes first.
+ */
+export declare function createRenderTimeout(timeoutMs: number, parentSignal?: AbortSignal): RenderTimeout;
+/**
+ * Race a promise against a timeout. Rejects with RenderTimeoutError
+ * if the promise does not resolve within `timeoutMs`.
+ *
+ * Used to guard individual `rscReader.read()` calls inside pullLoop.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, context?: string): Promise<T>;
+//# sourceMappingURL=render-timeout.d.ts.map

package/dist/server/render-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-timeout.d.ts","sourceRoot":"","sources":["../../src/server/render-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAO9C;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,MAAM,EAAE,WAAW,CAAC;IACpB,qEAAqE;IACrE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,WAAW,GAAG,aAAa,CA+BhG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/server/render-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared render-phase utilities — used by both the Node.js and Web
+ * stream wrappers. Pure functions only; no stream-shape dependencies.
+ *
+ * Consolidated from duplicated copies in node-stream-transforms.ts,
+ * ssr-render.ts, and rsc-entry/helpers.ts. See TIM-1071 item 1.
+ */
+/**
+ * Check if an error is an abort error (connection closed by client).
+ *
+ * When the browser aborts a request (page refresh, navigation away),
+ * the AbortSignal fires and React/streams throw an AbortError. This
+ * is not an application error — suppress it from error boundaries and logs.
+ */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Inline script that adds `<meta name="robots" content="noindex">` to the
+ * document head. Injected when a render-phase error replaces the shell so
+ * search engines don't index error pages.
+ *
+ * MUST be byte-identical across all stream wrappers (Node and Web) to
+ * ensure consistent Content-Length headers.
+ */
+export declare const NOINDEX_SCRIPT = "<script>document.head.appendChild(Object.assign(document.createElement(\"meta\"),{name:\"robots\",content:\"noindex\"}))</script>";
+//# sourceMappingURL=render-utils.d.ts.map

package/dist/server/render-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-utils.d.ts","sourceRoot":"","sources":["../../src/server/render-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIpD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,sIACoG,CAAC"}

package/dist/server/request-context.d.ts

@@ -1,140 +1,102 @@
 /**
- * Request Context — per-request ALS store for headers() and cookies().
+ * Request Context — per-request ALS store for headers, search params,
+ * segment params, and request scope lifecycle.
  *
  * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage
  * instance, public accessor functions that throw outside request scope,
  * and a framework-internal `runWithRequestContext()` to establish scope.
  *
+ * Cookie state lives in `cookie-context.ts` (split out in TIM-853). The
+ * scope set up here owns the cookie jar / parsedCookies fields on the
+ * store, but the cookie API and helpers are in the cookie module.
+ *
  * See design/04-authorization.md §"AccessContext does not include cookies or headers"
  * and design/11-platform.md §"AsyncLocalStorage".
- * See design/29-cookies.md for cookie mutation semantics.
  */
-import type { Routes } from '#/index.js';
 import { requestContextAls } from './als-registry.js';
 export { requestContextAls };
-/**
- * Configure the cookie signing secrets.
- *
- * Called by the framework during server initialization with values from
- * `cookies.secret` or `cookies.secrets` in timber.config.ts.
- *
- * The first secret (index 0) is used for signing new cookies.
- * All secrets are tried for verification (supports key rotation).
- */
-export declare function setCookieSecrets(secrets: string[]): void;
 /**
  * Returns a read-only view of the current request's headers.
  *
  * Available in middleware, access checks, server components, and server actions.
  * Throws if called outside a request context (security principle #2: no global fallback).
  */
-export declare function headers(): ReadonlyHeaders;
+export declare function getHeaders(): ReadonlyHeaders;
 /**
- * Returns a cookie accessor for the current request.
+ * Returns the value of a single request header, or undefined if absent.
  *
- * Available in middleware, access checks, server components, and server actions.
- * Throws if called outside a request context (security principle #2: no global fallback).
+ * Thin wrapper over `getHeaders().get(name)` for the common case where
+ * you need exactly one header.
+ *
+ * @internal — not part of the public API. Use `getHeaders().get(name)` instead.
+ */
+export declare function getHeader(name: string): string | undefined;
+/**
+ * Returns the current request's raw URLSearchParams.
+ *
+ * @internal — not part of the public API. Use `defineSearchParams().get()` instead.
+ */
+export declare function getSearchParams(): URLSearchParams;
+/**
+ * Returns the current request's coerced segment params.
  *
- * Read methods (.get, .has, .getAll) are always available and reflect
- * read-your-own-writes from .set() calls in the same request.
+ * The optional `segmentPath` argument exists only for TypeScript narrowing —
+ * it does not affect the runtime return value. Pass a segment path
+ * (e.g. `'/(browse)/[artistSlug]/[year]'`) to narrow the return type to the
+ * exact params shape for that segment.
  *
- * 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.
+ * Without an argument, returns all coerced params with optional types.
  *
- * See design/29-cookies.md
+ * See design/41-global-params.md §Function Signatures
  */
-export declare function cookies(): RequestCookies;
+export declare function getSegmentParams(segmentPath?: string): Record<string, string | string[]>;
 /**
- * Returns a Promise resolving to the current request's search params.
+ * Set the segment params on the current request context.
+ * Called by the pipeline after route matching and param coercion.
  *
- * In `page.tsx`, `middleware.ts`, and `access.ts` the framework pre-parses the
- * route's `search-params.ts` definition and the Promise resolves to the typed
- * object. In all other server component contexts it resolves to raw
- * `URLSearchParams`.
+ * @internal — framework use only
+ */
+export declare function setSegmentParams(params: Record<string, string | string[]>): void;
+/**
+ * Store per-slot coerced segment params in the current request context.
+ * Called by the route element builder when resolving parallel slots.
  *
- * Returned as a Promise to match the `params` prop convention and to allow
- * future partial pre-rendering support where param resolution may be deferred.
+ * @param segmentPath — The slot's full tree path (e.g. '/(browse)/@shows/[artistSlug]/[...year]')
+ * @param params — The slot's coerced segment params
+ * @internal — framework use only
+ */
+export declare function setSlotParams(segmentPath: string, params: Record<string, string | string[]>): void;
+/**
+ * Store the matched segment path (e.g. '/(browse)/[artistSlug]/[year]') for
+ * dev-mode validation in getSegmentParams().
  *
- * Throws if called outside a request context.
+ * @internal — framework use only
  */
-export declare function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>;
-export declare function searchParams(): Promise<URLSearchParams | Record<string, unknown>>;
+export declare function setMatchedSegmentPath(segmentPath: string): void;
 /**
- * Replace the search params Promise for the current request with one that
- * resolves to the typed parsed result from the route's search-params.ts.
- * Called by the framework before rendering the page — not for app code.
+ * 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 declare function setParsedSearchParams(parsed: Record<string, unknown>): void;
+export declare function getRequestSearchString(): string;
 /**
  * Read-only Headers interface. The standard Headers class is mutable;
  * this type narrows it to read-only methods. The underlying object is
  * still a Headers instance, but user code should not mutate it.
  */
 export type ReadonlyHeaders = Pick<Headers, 'get' | 'has' | 'entries' | 'keys' | 'values' | 'forEach' | typeof Symbol.iterator>;
-/** 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;
-    /**
-     * Sign the cookie value with HMAC-SHA256 for integrity verification.
-     * Requires `cookies.secret` or `cookies.secrets` in timber.config.ts.
-     * See design/29-cookies.md §"Signed Cookies".
-     */
-    signed?: boolean;
-}
-/**
- * Cookie accessor returned by `cookies()`.
- *
- * 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;
-    /**
-     * Get a signed cookie value, verifying its HMAC-SHA256 signature.
-     * Returns undefined if the cookie is missing, the signature is invalid,
-     * or no secrets are configured. Never throws.
-     *
-     * See design/29-cookies.md §"Signed Cookies"
-     */
-    getSigned(name: string): string | undefined;
-    /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */
-    set(name: string, value: string, options?: CookieOptions): 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;
-}
 /**
  * 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.
+ *
+ * If the request was previously registered via `seedRequestCookies`, the
+ * resulting context's `parsedCookies` map is initialized from the seed and
+ * the raw `cookieHeader` is left empty — `parseCookieHeader` is never called
+ * for that request. This is the no-JS form-rerender path. See TIM-868.
  *
  * @param req - The incoming Request object.
  * @param fn - The function to run within the request context.
@@ -154,19 +116,12 @@ export declare function setMutableCookieContext(mutable: boolean): void;
  * See design/29-cookies.md §"Streaming Constraint: Post-Flush Cookie Warning"
  */
 export declare function markResponseFlushed(): void;
-/**
- * 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 declare function getSetCookieHeaders(): string[];
 /**
  * Apply middleware-injected request headers to the current request context.
  *
  * 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.

package/dist/server/request-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAA4B,MAAM,mBAAmB,CAAC;AAOhF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAI7B;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAS5C;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CASjD;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CA+CxF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAMhF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GACxC,IAAI,CAKN;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAI/D;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAG/C;AAID;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,OAAO,EACP,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,MAAM,CAAC,QAAQ,CACnF,CAAC;AAIF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAmBrE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK9D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmBhE"}

package/dist/server/route-element-builder.d.ts

@@ -6,9 +6,9 @@
  * rsc-entry.ts under the 500-line limit.
  *
  * This module handles:
- * 1. Loading page/layout components from the segment chain
- * 2. Running access.ts checks (DenySignal/RedirectSignal propagate to caller)
- * 3. Resolving metadata (static object or async function, both exported as `metadata`)
+ * 1. Running access.ts checks eagerly to gate metadata resolution (TIM-1027)
+ * 2. Loading page/layout components from the segment chain
+ * 3. Resolving metadata (skipped for denied segments to prevent side effects)
  * 4. Building the React element tree (page → error boundaries → access gates → layouts)
  * 5. Resolving parallel slots
  *
@@ -16,13 +16,40 @@
  */
 import type { RouteMatch } from './pipeline.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
-import { DenySignal, RedirectSignal } from './primitives.js';
 import type { InterceptionContext } from './pipeline.js';
-/** Head element for client-side metadata updates. */
-export interface HeadElement {
-    tag: string;
-    content?: string;
-    attrs?: Record<string, string | null>;
+import type { HeadElement } from './metadata.js';
+/**
+ * Convert HeadElement descriptors to React elements for Float hoisting.
+ *
+ * React 19 Float hoists <title>, <meta>, and <link> rendered anywhere in
+ * the tree into <head> during SSR, and manages them in document.head
+ * during client-side rendering. This replaces the X-Timber-Head header
+ * side-channel and the imperative client DOM applier.
+ */
+export declare function headElementsToReact(elements: HeadElement[]): React.ReactElement;
+/**
+ * Detect whether a component is a React client reference.
+ * Client references have $$typeof set to Symbol.for('react.client.reference')
+ * by registerClientReference() in the React Flight server runtime.
+ *
+ * Used to skip OTEL tracing wrappers that would call the component as a
+ * function. Client components must go through createElement only — they are
+ * serialized as references in the RSC Flight stream, not executed on the server.
+ */
+export declare function isClientReference(component: unknown): boolean;
+/**
+ * Thrown when a defineSegmentParams codec's parse() fails.
+ * The pipeline catches this and responds with 404.
+ */
+export declare class ParamCoercionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a matched route has no page component in its leaf segment.
+ * The pipeline catches this and renders the custom 404 page.
+ */
+export declare class NoPageComponentError extends Error {
+    constructor(message: string);
 }
 /** Layout entry with component and segment. */
 export interface LayoutComponentEntry {
@@ -33,8 +60,6 @@ export interface LayoutComponentEntry {
 export interface RouteElementResult {
     /** The React element tree (page wrapped in layouts, access gates, error boundaries). */
     element: React.ReactElement;
-    /** Resolved head elements for metadata. */
-    headElements: HeadElement[];
     /** Layout components loaded along the segment chain. */
     layoutComponents: LayoutComponentEntry[];
     /** Segments from the route match. */
@@ -48,26 +73,31 @@ export interface RouteElementResult {
      * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
      */
     skippedSegments: string[];
-}
-/**
- * Wraps a DenySignal or RedirectSignal with the layout components loaded
- * so far, enabling the caller to render deny pages inside the layout shell.
- */
-export declare class RouteSignalWithContext extends Error {
-    readonly signal: DenySignal | RedirectSignal;
-    readonly layoutComponents: LayoutComponentEntry[];
-    readonly segments: ManifestSegmentNode[];
-    constructor(signal: DenySignal | RedirectSignal, layoutComponents: LayoutComponentEntry[], segments: ManifestSegmentNode[]);
+    /**
+     * Resolves when every deny-capable shell component (PageDenyBoundary and
+     * each TracedLayout with a deny page chain) has finished executing, OR
+     * immediately when any of them catches a DenySignal in-tree (the HTTP
+     * status is known at that point; inner components may never run).
+     * Undefined when the route has no deny-capable server components.
+     * See TIM-1045 (pages), TIM-1208 (layouts).
+     */
+    shellSettled?: Promise<void>;
 }
 /**
  * Build a React element tree from a matched route.
  *
- * Loads modules, runs access checks, resolves metadata, and constructs
- * the element tree. DenySignal and RedirectSignal propagate to the caller
- * for HTTP-level handling.
+ * Runs access checks eagerly to gate metadata resolution, then loads
+ * modules, resolves metadata (skipping denied segments), and constructs
+ * the element tree. DenySignal and RedirectSignal from access are stored
+ * as AccessGate verdicts for synchronous replay during render.
  *
  * Does NOT serialize to RSC Flight — the caller decides whether to render
  * to a stream or use the element directly (e.g., for action revalidation).
+ *
+ * For passing segments, AccessGate re-runs access during render so that
+ * React.cache is populated for layout dedup (TIM-662). For denied
+ * segments, the pre-computed verdict is replayed — no re-execution,
+ * no metadata side effects, no head leak (TIM-1027).
  */
-export declare function buildRouteElement(req: Request, match: RouteMatch, interception?: InterceptionContext, clientStateTree?: Set<string> | null): Promise<RouteElementResult>;
+export declare function buildRouteElement(req: Request, match: RouteMatch, interception?: InterceptionContext, clientStateTree?: Set<string> | null, metadataRouteHashes?: Record<string, string>): Promise<RouteElementResult>;
 //# sourceMappingURL=route-element-builder.d.ts.map