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

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

@@ -1,145 +1,177 @@
 /**
- * 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';
+import type { CoercedParams } from '../shared/param-value.ts';
+import { requestContextAls } from './als-registry.ts';
+import { type SlotParamsRecord } from '../shared/slot-params.ts';
+import { type ReactCacheScope } from './react-cache-scope.ts';
 export { requestContextAls };
 /**
- * Configure the cookie signing secrets.
+ * Returns a read-only view of the current request's headers.
  *
- * Called by the framework during server initialization with values from
- * `cookies.secret` or `cookies.secrets` in timber.config.ts.
+ * 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 getHeaders(): ReadonlyHeaders;
+/**
+ * Returns the value of a single request header, or undefined if absent.
+ *
+ * Thin wrapper over `getHeaders().get(name)` for the common case where
+ * you need exactly one header.
  *
- * The first secret (index 0) is used for signing new cookies.
- * All secrets are tried for verification (supports key rotation).
+ * @internal — not part of the public API. Use `getHeaders().get(name)` instead.
  */
-export declare function setCookieSecrets(secrets: string[]): void;
+export declare function getHeader(name: string): string | undefined;
 /**
- * Returns a read-only view of the current request's headers.
+ * Returns the current request's raw URLSearchParams.
  *
- * Available in middleware, access checks, server components, and server actions.
- * Throws if called outside a request context (security principle #2: no global fallback).
+ * @internal — not part of the public API. Use `defineSearchParams().get()` instead.
  */
-export declare function headers(): ReadonlyHeaders;
+export declare function getSearchParams(): URLSearchParams;
 /**
- * Returns a cookie accessor for the current request.
+ * Returns the current request's coerced segment params.
  *
- * Available in middleware, access checks, server components, and server actions.
- * Throws if called outside a request context (security principle #2: no global fallback).
+ * 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.
+ *
+ * Without an argument, returns all coerced params with optional types.
+ *
+ * See design/41-global-params.md §Function Signatures
+ */
+export declare function getSegmentParams(segmentPath?: string): CoercedParams;
+/**
+ * Set the segment params on the current request context.
+ * Called by the pipeline after route matching and param coercion.
+ *
+ * @internal — framework use only
+ */
+export declare function setSegmentParams(params: CoercedParams): void;
+/**
+ * Store per-slot coerced segment params in the current request context.
+ * Called by the route element builder when resolving parallel slots.
  *
- * Read methods (.get, .has, .getAll) are always available and reflect
- * read-your-own-writes from .set() calls in the same request.
+ * @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: CoercedParams): void;
+/**
+ * Run `fn` with the segment params a parallel slot's own chain produced, so
+ * a no-arg `getSegmentParams()` inside that slot returns the slot's params
+ * rather than the main route's.
+ *
+ * ALS is the only channel available: the slot's page and layouts are plain
+ * components that receive no params prop and cannot know their own tree
+ * path, so they have no way to ask for the keyed overload. The slot resolver
+ * invokes each of them itself (page through `SafeSlotPage`, layouts and
+ * access functions through their wrappers), and this scopes those calls.
+ *
+ * The store is wrapped in a Proxy rather than cloned. Everything a slot
+ * renders can write to the *live* request store — `setDenyStatus` from an
+ * access gate, cookie writes, the flush flag — and a clone would silently
+ * strand those writes in a copy the pipeline never reads. Only the two
+ * params fields are shadowed; every other read and every write passes
+ * straight through to the real store.
+ *
+ * Returns `fn()`'s result unchanged, and no-ops outside a request context or
+ * before route matching has set the main params. See TIM-1283.
+ *
+ * @internal — framework use only
+ */
+export declare function runWithSlotSegmentParams<T>(slotSegmentPath: string | undefined, slotParams: CoercedParams, fn: () => T): T;
+/**
+ * The main route's coerced params, or an empty record before route matching.
  *
- * 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.
+ * Non-throwing, unlike `getSegmentParams()`: the deny payload path publishes
+ * params from wherever the pipeline happened to fail, which may be before
+ * matching completed.
  *
- * See design/29-cookies.md
+ * @internal — framework use only. See TIM-1285.
  */
-export declare function cookies(): RequestCookies;
+export declare function getSegmentParamsForClient(): CoercedParams;
 /**
- * Returns a Promise resolving to the current request's search params.
+ * The per-slot params to publish to the client, or `undefined` when the
+ * request rendered no slot with params of its own.
  *
- * 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`.
+ * The client cannot derive these: a slot matches the URL through its own
+ * sub-tree, and the browser only ever sees the main route's record. Reading
+ * the map here — rather than threading it back out of the element builder —
+ * keeps one producer, since `setSlotParams` already writes it during slot
+ * resolution and every serialization site runs after that completes.
  *
- * Returned as a Promise to match the `params` prop convention and to allow
- * future partial pre-rendering support where param resolution may be deferred.
+ * @internal — framework use only. See TIM-1285.
+ */
+export declare function getSlotParamsForClient(): SlotParamsRecord | undefined;
+/**
+ * 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;
+/** Options for `runWithRequestContext()`. */
+export interface RequestContextOptions {
     /**
-     * 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".
+     * Resume this `React.cache` scope instead of opening a fresh one. Only the
+     * post-action revalidation passes it.
      */
-    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;
+    reactCacheScope?: ReactCacheScope;
     /**
-     * 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"
+     * The request's cookies, already parsed. Re-entry callers (the no-JS form
+     * rerender and the revalidation middleware) pass the action's
+     * post-mutation cookie state here instead of round-tripping it through a
+     * `Cookie:` header — the same parse the H-3 smuggling primitive abused
+     * (TIM-868).
      */
-    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;
+    cookies?: Map<string, 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.
+ *
+ * When `options.cookies` is given, the context's `parsedCookies` map is a
+ * copy of it and the raw `cookieHeader` is left empty, so
+ * `parseCookieHeader` never runs for that request. Re-entry callers pass the
+ * action's post-mutation cookie state this way (TIM-868).
+ *
+ * Each request context also opens its own `React.cache` scope, shared by
+ * everything that runs inside it — proxy.ts, middleware.ts, route handlers,
+ * and the render (design/02-rendering-pipeline.md §"Cache Scoping Model").
  *
  * @param req - The incoming Request object.
  * @param fn - The function to run within the request context.
  */
-export declare function runWithRequestContext<T>(req: Request, fn: () => T): T;
+export declare function runWithRequestContext<T>(req: Request, fn: () => T, { reactCacheScope, cookies }?: RequestContextOptions): T;
 /**
  * Enable cookie mutation for the current context. Called by the framework
  * when entering middleware.ts, server actions, or route.ts handlers.
@@ -154,19 +186,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,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAA4B,MAAM,mBAAmB,CAAC;AAGhF,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGtF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAI7B;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAU5C;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAUjD;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,CA2CpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAK9E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,UAAU,EAAE,aAAa,EACzB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAcH;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,IAAI,aAAa,CAEzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,GAAG,SAAS,CAIrE;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,6CAA6C;AAC7C,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,GAAG,EAAE,OAAO,EACZ,EAAE,EAAE,MAAM,CAAC,EACX,EAAE,eAAe,EAAE,OAAO,EAAE,GAAE,qBAA0B,GACvD,CAAC,CAyBH;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/request-dep.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Static request-dependency lookup.
+ *
+ * Queries the Vite plugin's precomputed module-graph analysis to determine
+ * whether a segment's entry file (layout/page/default) is request-dependent.
+ *
+ * In dev: the plugin registers a resolver function via Symbol.for bridge
+ * that lazily walks the RSC module graph.
+ * In prod: reads from the build manifest's requestDep map (set during build
+ * and serialized into the manifest init script by the adapter).
+ *
+ * Returns true (conservative) when no data is available.
+ */
+export declare function isStaticRequestDependent(filePath: string): boolean;
+//# sourceMappingURL=request-dep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"request-dep.d.ts","sourceRoot":"","sources":["../../src/server/request-dep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAkBlE"}

package/dist/server/response-cache-policy.d.ts

@@ -0,0 +1,3 @@
+/** Disable caching, including CDN overrides that take precedence over Cache-Control. */
+export declare function preventResponseCaching(headers: Headers): void;
+//# sourceMappingURL=response-cache-policy.d.ts.map

package/dist/server/response-cache-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-cache-policy.d.ts","sourceRoot":"","sources":["../../src/server/response-cache-policy.ts"],"names":[],"mappings":"AAgCA,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAW7D"}

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

@@ -6,23 +6,41 @@
  * 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
  *
  * See design/02-rendering-pipeline.md, design/04-authorization.md
  */
-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 { RouteMatch } from './pipeline.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { DenyPageEntry } from './deny-boundary.ts';
+import { type SlotSkipEntry } from './slot-resolver.ts';
+import type { RscPayloadRoot } from '../shared/payload-root.ts';
+import type { InterceptionContext } from './pipeline.ts';
+import type { ClientStateTree } from './state-tree-diff.ts';
+/**
+ * The `segments` array handed to a layout's `SegmentProvider` — the value
+ * `useSelectedLayoutSegment(s)` reads.
+ *
+ * Only its **length** matters: both hooks take `segments.length` as a depth and
+ * index the live pathname with it. So this is really "how many URL parts had
+ * been consumed by the time this layout rendered", which is
+ * `consumedUrlParts` — the same derivation slot matching and the slot-skip
+ * slicing use, so a layout and the slots beside it cannot disagree about how
+ * deep they are. The root consumes nothing → `['']`, length 1.
+ *
+ * @internal — exported for tests; production has exactly one caller.
+ */
+export declare function computeLayoutSegmentPath(segments: ManifestSegmentNode[], index: number, match: RouteMatch): 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 {
@@ -31,10 +49,12 @@ export interface LayoutComponentEntry {
 }
 /** Result of building a route element tree. */
 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[];
+    /**
+     * The payload root: the React element tree (page wrapped in layouts, access
+     * gates, error boundaries) plus the params it rendered with, as siblings.
+     * See shared/payload-root.ts for why params are not a wrapper around it.
+     */
+    payload: RscPayloadRoot;
     /** Layout components loaded along the segment chain. */
     layoutComponents: LayoutComponentEntry[];
     /** Segments from the route match. */
@@ -48,26 +68,33 @@ 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[]);
+    /**
+     * Slot metadata for the X-Timber-Segments header. Contains info about
+     * all parallel route slots encountered during element tree construction,
+     * enabling the client to populate its segment cache with slot entries.
+     */
+    slotSkipInfo: SlotSkipEntry[];
+    /**
+     * The deny page chain built from the leaf segment outward to root.
+     * Threaded into `renderRscStream` for late addressing of nested-component
+     * denies in Flight's `onError`. See TIM-1450.
+     */
+    leafDenyChain?: DenyPageEntry[];
 }
 /**
  * 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.
+ * Loads route modules, resolves metadata (skipping denied segments via
+ * AccessGate), and constructs the element tree. Access checks run during
+ * render inside AccessGate — denied segments' metadata never executes.
  *
  * 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?: ClientStateTree | null, metadataRouteHashes?: Record<string, string>): Promise<RouteElementResult>;
 //# sourceMappingURL=route-element-builder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAKzD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAsW7B"}
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQ9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAMhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAQ5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,GAChB,MAAM,EAAE,CAGV;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAID,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;OAIG;IACH,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC;CACjC;AA2DD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,EACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,OAAO,CAAC,kBAAkB,CAAC,CA6Z7B"}

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

@@ -0,0 +1,12 @@
+/**
+ * Pure helpers for `route-element-builder.ts` — tree inspection and rewriting
+ * that need no request state. Split out so the builder stays within the
+ * 500-line limit as its wrapping steps grew (TIM-1450).
+ */
+/**
+ * Replace the outermost SegmentOutlet in a partial payload with its
+ * SegmentProvider child. Walks through AccessGate wrappers (which sit
+ * outside SegmentOutlet) to find the outlet.
+ */
+export declare function replaceOutermostSegmentOutlet(element: React.ReactElement, replacement: React.ReactElement): React.ReactElement;
+//# sourceMappingURL=route-element-helpers.d.ts.map

package/dist/server/route-element-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-element-helpers.d.ts","sourceRoot":"","sources":["../../src/server/route-element-helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,KAAK,CAAC,YAAY,EAC3B,WAAW,EAAE,KAAK,CAAC,YAAY,GAC9B,KAAK,CAAC,YAAY,CAgBpB"}

package/dist/server/route-handler.d.ts

@@ -7,7 +7,7 @@
  *
  * See design/07-routing.md §"route.ts — API Endpoints"
  */
-import type { RouteContext } from './types.js';
+import type { RouteContext } from './types.ts';
 /** HTTP methods that route.ts can export as named handlers. */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 /** A single route handler function — one-arg signature. */

package/dist/server/route-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-handler.d.ts","sourceRoot":"","sources":["../../src/server/route-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE/E,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,YAAY;CACjC,CAAC;AAOF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,EAAE,CAyBpE;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyC/F"}
+{"version":3,"file":"route-handler.d.ts","sourceRoot":"","sources":["../../src/server/route-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE/E,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,YAAY;CACjC,CAAC;AAOF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,EAAE,CAyBpE;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyC/F"}