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

package/dist/server/pipeline.d.ts

@@ -2,48 +2,104 @@
  * Request pipeline — the central dispatch for all timber.js requests.
  *
  * Pipeline stages (in order):
- *   proxy.ts → canonicalize → route match → 103 Early Hints → middleware.ts → render
+ *   canonicalize → CSRF gate → proxy.ts → route match → 103 Early Hints → middleware.ts → render
  *
- * Each stage is a pure function or returns a Response to short-circuit.
- * Each request gets a trace ID, structured logging, and OTEL spans.
+ * The phase functions live in `pipeline-phases.ts` so each phase can be
+ * tested in isolation. The terminal `outcomeToResponse` translator and
+ * stateless helpers live in `pipeline-phases.ts` and `pipeline-helpers.ts`
+ * respectively. This file owns only the public type surface and the
+ * `createPipeline` entry point: trace ID setup, request-context ALS,
+ * Server-Timing wrapping, and the activeRequests counter.
  *
  * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow",
  * and design/17-logging.md §"Production Logging"
  */
-import { type ProxyExport } from './proxy.js';
-import { type MiddlewareFn } from './middleware-runner.js';
-import type { SegmentNode } from '#/routing/types.js';
-/** Result of matching a canonical pathname against the route tree. */
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { ProxyExport } from './proxy.ts';
+import type { MiddlewareFn } from './middleware-runner.ts';
+import { DenySignal } from './primitives.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { CsrfConfig } from './csrf.ts';
+/**
+ * Result of matching a canonical pathname against the route tree.
+ *
+ * `segments` is the runtime (`ManifestFile`-specialized) shape — the same
+ * nodes carried in the virtual route manifest. TIM-863 unified this: the
+ * matcher produces `ManifestSegmentNode[]` directly and every consumer
+ * (render, slots, params coercion, early hints, deny fallback) sees the
+ * same structural type with no `as unknown as` laundering.
+ */
 export interface RouteMatch {
     /** The matched segment chain from root to leaf. */
-    segments: SegmentNode[];
-    /** Extracted route params (catch-all segments produce string[]). */
-    params: Record<string, string | string[]>;
-    /** The leaf segment's middleware.ts export, if any. */
-    middleware?: MiddlewareFn;
+    segments: ManifestSegmentNode[];
+    /**
+     * Segment params as the page sees them. The matcher sets them to the raw
+     * values; whoever runs `coerceSegmentParams()` replaces them with its
+     * result, whose values may be non-string (TIM-1347).
+     */
+    segmentParams: CoercedParams;
+    /**
+     * Segment params as the URL carried them (catch-all segments produce
+     * string[]). Set by the matcher, which owns them, and never replaced.
+     * Slot resolution and URL-part reconstruction read these: coerced values
+     * need not round-trip to the URL (`"007"` → `7`).
+     */
+    rawSegmentParams: Record<string, string | string[]>;
+    /** Middleware chain from the segment tree, ordered root-to-leaf. */
+    middlewareChain: MiddlewareFn[];
 }
 /** Function that matches a canonical pathname to a route. */
 export type RouteMatcher = (pathname: string) => RouteMatch | null;
 /** Function that matches a canonical pathname to a metadata route. */
-export type MetadataRouteMatcher = (pathname: string) => import('./route-matcher.js').MetadataRouteMatch | null;
+export type MetadataRouteMatcher = (pathname: string) => import('./route-matcher.ts').MetadataRouteMatch | null;
 /** Context for intercepting route resolution (modal pattern). */
 export interface InterceptionContext {
     /** The URL the user is navigating TO (the intercepted route). */
     targetPathname: string;
 }
 /** Function that renders a matched route into a Response. */
-export type RouteRenderer = (req: Request, match: RouteMatch, responseHeaders: Headers, requestHeaderOverlay: Headers, interception?: InterceptionContext) => Response | Promise<Response>;
+export type RouteRenderer = (req: Request, match: RouteMatch, responseHeaders: Headers, interception?: InterceptionContext) => Response | Promise<Response>;
 /** Function that sends 103 Early Hints for a matched route. */
 export type EarlyHintsEmitter = (match: RouteMatch, req: Request, responseHeaders: Headers) => void | Promise<void>;
-export interface PipelineConfig {
-    /** The proxy.ts default export (function or array). Undefined if no proxy.ts. */
-    proxy?: ProxyExport;
-    /** Lazy loader for proxy.ts — called per-request so HMR updates take effect. */
-    proxyLoader?: () => Promise<{
+/**
+ * Proxy source — a tagged union so the choice between "already-resolved
+ * export" and "lazy HMR-friendly loader" is encoded in the type, not
+ * inferred per-request.
+ *
+ * - `static` — the proxy export is already resolved (production, tests).
+ * - `lazy`   — a loader is called per-request for HMR freshness (dev).
+ *
+ * `PipelineConfig.proxy` also accepts a bare `ProxyExport` (a function or
+ * function array) as shorthand for the static variant — convenient for tests
+ * that construct a `createPipeline` config inline. Omit the field entirely
+ * when the app has no `proxy.ts`.
+ *
+ * See design/07-routing.md §"proxy.ts — Global Middleware".
+ */
+export type ProxyConfig = {
+    kind: 'static';
+    export: ProxyExport;
+} | {
+    kind: 'lazy';
+    loader: () => Promise<{
         default: ProxyExport;
     }>;
+};
+export interface PipelineConfig {
+    /**
+     * proxy.ts source. Undefined if the app has no proxy.ts. Accepts either a
+     * tagged `ProxyConfig` (canonical) or a bare `ProxyExport` as sugar for the
+     * static variant.
+     */
+    proxy?: ProxyConfig | ProxyExport;
     /** Route matcher — resolves a canonical pathname to a RouteMatch. */
     matchRoute: RouteMatcher;
+    /**
+     * CSRF configuration (`allowedOrigins`, the `csrf: false` switch). The
+     * gate is on when this is omitted — protection is never opt-in. See
+     * design/08-forms-and-actions.md §"CSRF Protection".
+     */
+    csrf?: CsrfConfig;
     /** Metadata route matcher — resolves metadata route pathnames (sitemap.xml, robots.txt, etc.) */
     matchMetadataRoute?: MetadataRouteMatcher;
     /** Renderer — produces the final Response for a matched route. */
@@ -61,7 +117,18 @@ export interface PipelineConfig {
      * Generated at build time from intercepting route directories.
      * See design/07-routing.md §"Intercepting Routes"
      */
-    interceptionRewrites?: import('#/routing/interception.js').InterceptionRewrite[];
+    interceptionRewrites?: import('../routing/interception.ts').InterceptionRewrite[];
+    /**
+     * Resolver for children-path interceptions — the sibling layout swap.
+     *
+     * Separate from `matchRoute` because it addresses the owner directory by
+     * tree path rather than by pathname, which needs the manifest tree itself.
+     * Omitting it disables the `'children'` interception shape and leaves the
+     * canonical route rendering, which is the fail-safe outcome.
+     *
+     * See design/07-routing.md §"Intercepting Routes"
+     */
+    matchInterceptedRoute?: import('./children-interception.ts').InterceptedRouteMatcher;
     /**
      * Control Server-Timing header output.
      *
@@ -72,6 +139,14 @@ export interface PipelineConfig {
      * Default: `'total'`.
      */
     serverTiming?: 'detailed' | 'total' | false;
+    /**
+     * Auto-generated sitemap handler. When provided, the pipeline intercepts
+     * `/sitemap.xml` and `/sitemap/N.xml` requests and delegates to this
+     * function. Returns a Response or null (pass-through to regular routing).
+     *
+     * See design/16-metadata.md §"Auto-generated Sitemap"
+     */
+    autoSitemapHandler?: (pathname: string) => Promise<Response | null>;
     /**
      * Dev pipeline error callback — called when a pipeline phase (proxy,
      * middleware, render) catches an unhandled error. Used to wire the error
@@ -91,13 +166,62 @@ export interface PipelineConfig {
      * If this function throws, the pipeline falls back to a bare
      * `new Response(null, { status: 500 })`.
      */
-    renderFallbackError?: (error: unknown, req: Request, responseHeaders: Headers) => Response | Promise<Response>;
+    renderFallbackError?: (error: unknown, req: Request, responseHeaders: Headers, 
+    /**
+     * The matched route, when the error came after matching. A route.ts
+     * match is answered in the API route's JSON format, never a page
+     * (design/10-error-handling.md §"JSON Error Pages").
+     */
+    match?: RouteMatch) => Response | Promise<Response>;
+    /**
+     * Fallback deny page renderer — called when a DenySignal escapes from
+     * middleware or the render phase. Renders the appropriate status-code
+     * page (403.tsx, 404.tsx, etc.) instead of returning a bare empty response.
+     *
+     * If this function throws, the pipeline falls back to a bare
+     * `new Response(null, { status: denyStatus })`.
+     */
+    renderDenyFallback?: (deny: DenySignal, req: Request, responseHeaders: Headers, 
+    /**
+     * The matched route, if available. Provided by both the middleware-stage
+     * and render-stage catch blocks (matching runs before middleware). When
+     * present, the renderer should resolve the deny status file against the
+     * matched chain so colocated `403.tsx`/`4xx.tsx`/`401.json` files are
+     * picked up. Falls back to the root-only chain when omitted (e.g. for
+     * deny()s thrown before route matching could complete). See TIM-822.
+     */
+    match?: RouteMatch) => Response | Promise<Response>;
+    /**
+     * Server action dispatch — called after proxy.ts runs for POST requests
+     * that look like server actions. Returns a Response if the request was
+     * handled as an action, or null to fall through to normal routing.
+     *
+     * `canonicalPath` is the already-decoded canonical pathname — the same
+     * value that `handleRequest` and `matchRoute` use. Do NOT re-derive it
+     * from `req.url` (which re-encodes).
+     *
+     * The `reenter` parameter is the full pipeline function (including proxy,
+     * ALS, tracing) for the no-JS validation rerender path — the synthetic
+     * GET flows through the complete pipeline. Its `cookies` argument becomes
+     * that request's parsed cookies (`runWithRequestContext`'s `cookies`
+     * option), so the rerender reads the action's post-mutation state without
+     * the pipeline needing the same `Request` object to reach it.
+     *
+     * Moved into the pipeline (TIM-1213) so proxy.ts runs on action POSTs,
+     * matching the design doc contract: "proxy.ts runs on every request,
+     * no exclusions."
+     */
+    dispatchAction?: (req: Request, canonicalPath: string, reenter: (req: Request, cookies: Map<string, string>) => Promise<Response>) => Promise<Response | null>;
 }
 /**
  * Create the request handler from a pipeline configuration.
  *
- * Returns a function that processes an incoming Request through all pipeline stages
- * and produces a Response. This is the top-level entry point for the server.
+ * Returns a function that processes an incoming Request through all pipeline
+ * stages and produces a Response. This is the top-level entry point for the
+ * server. The body is intentionally small — phase logic lives in
+ * `pipeline-phases.ts`. This function only owns the per-request setup that
+ * has to wrap the entire dispatch: trace ID, request context ALS, span
+ * scope, Server-Timing header emission, and the active-request counter.
  */
 export declare function createPipeline(config: PipelineConfig): (req: Request) => Promise<Response>;
 //# sourceMappingURL=pipeline.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/server/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAgC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,uDAAuD;IACvD,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAAC;AAEnE,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,CACjC,QAAQ,EAAE,MAAM,KACb,OAAO,oBAAoB,EAAE,kBAAkB,GAAG,IAAI,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,YAAY,CAAC,EAAE,mBAAmB,KAC/B,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAI1B,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACtD,qEAAqE;IACrE,UAAU,EAAE,YAAY,CAAC;IACzB,iGAAiG;IACjG,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzF,kFAAkF;IAClF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yGAAyG;IACzG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,2BAA2B,EAAE,mBAAmB,EAAE,CAAC;IACjF;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,KAAK,CAAC;IAC5C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,CACpB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,KACrB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnC;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuW1F"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/server/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/server/port-resolution.d.ts

@@ -0,0 +1,31 @@
+/** Port input precedence for dev and preview. Vite owns binding and restart reuse. */
+/** Default port used by `timber dev` and `timber preview`. */
+export declare const DEFAULT_PORT = 3000;
+export interface ResolvePortInput {
+    /**
+     * Port read from `vite.config.ts` `server.port` or the `--port` CLI
+     * flag (Vite merges `--port` into `userConfig.server.port` before
+     * plugins see it).
+     */
+    configPort?: number | undefined;
+    /** Raw value of `process.env.PORT`. */
+    envPort?: string | undefined;
+    /** Default port to use when neither `configPort` nor `envPort` is set. */
+    defaultPort?: number;
+}
+export interface ResolvedPortInput {
+    /** Port to start binding from. */
+    port: number;
+    /**
+     * `true` if the port came from an explicit user override (config or
+     * env). Preview uses this to default to strict port binding.
+     */
+    explicit: boolean;
+}
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O.
+ */
+export declare function resolveStartPort(input: ResolvePortInput): ResolvedPortInput;
+//# sourceMappingURL=port-resolution.d.ts.map

package/dist/server/port-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-resolution.d.ts","sourceRoot":"","sources":["../../src/server/port-resolution.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,8DAA8D;AAC9D,eAAO,MAAM,YAAY,OAAO,CAAC;AAIjC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAiB3E"}

package/dist/server/prebuilt/cache-key.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Component cache-key hashing for prebuilt (cache.component) entries.
+ *
+ * Key: `sha256(canonicalJson({ props, params })).slice(0, 16)` — see
+ * design/44-render-at-build-time.md §Cache Key. Both the request-time
+ * lookup (prebuilt-runtime.ts) and the post-build capture pass (TIM-1119)
+ * MUST use this exact function, or build artifacts become unaddressable.
+ *
+ * THE IDENTITY CONTRACT (design/44 §Cache Key): cache identity is **JSON
+ * value semantics** — two inputs are the same entry iff they are the same
+ * JSON value. This is an ALLOWLIST, not a denylist: a value participates
+ * in caching iff it is plain JSON data — null, boolean, finite number,
+ * string, dense array, or a plain `Object.prototype` object with only
+ * enumerable string-keyed data properties — plus `undefined` and `-0`,
+ * which hash as distinct sentinels because flight preserves them. Every
+ * value outside that domain (functions, symbols, bigints, accessors,
+ * hidden or symbol-keyed properties, non-`Object.prototype` prototypes
+ * including null, aliased references, sparse arrays, cycles, non-finite
+ * numbers) is UNKEYABLE by definition: `computeComponentCacheKey` returns
+ * null and the caller renders live — slower, never wrong.
+ *
+ * The line between rejected and declared-out-of-domain: values are
+ * REJECTED when the JSON projection itself would be ambiguous or lossy
+ * (hidden/symbol/non-enumerable properties, accessors, exotic
+ * prototypes). Observable state that leaves the projection intact — key
+ * order, reference identity, descriptor metadata (writable/configurable,
+ * frozen/sealed/extensible), proxy behavior — is DECLARED outside
+ * cache.component's supported input domain rather than rejected:
+ * key-order insensitivity is required for determinism, and rejecting
+ * frozen objects would unkey ubiquitous legitimate inputs
+ * (Object.freeze'd config props) to defend against components that
+ * render differently based on property attributes.
+ *
+ * Two hard rules for this walk itself: it must be TOTAL (never throw
+ * anything but UnkeyableValueError) and SIDE-EFFECT-FREE (descriptor
+ * reads only; never invoke user code such as getters).
+ *
+ * Object keys sort recursively so `{a, b}` and `{b, a}` hash identically
+ * (design/13-security.md checklist #14 — cache key determinism; key order
+ * is deliberately NOT part of identity).
+ */
+import type { CoercedParams } from '../../shared/param-value.ts';
+/**
+ * Canonicalize a single value, or null if it is unkeyable. The ONE
+ * definition of "faithfully comparable" — every prebuilt code path that
+ * needs value equality (cache keys, slot-param divergence) goes through
+ * this, so the unkeyable rules (accessors, hidden props, aliases,
+ * bigints, …) live in exactly one place.
+ */
+export declare function tryCanonicalize(value: unknown): string | null;
+export declare function splitSlotProps(props: Record<string, unknown>, slots: readonly string[]): {
+    dataProps: Record<string, unknown>;
+    slotValues: Record<string, unknown>;
+} | null;
+/**
+ * Compute the cache-entry hash for a component render:
+ * `sha256({props, params}).slice(0, 16)` over canonical JSON.
+ *
+ * Returns null when props (or params) contain unkeyable values — the
+ * caller must fall back to dynamic rendering.
+ */
+export declare function computeComponentCacheKey(props: Record<string, unknown>, params: CoercedParams): string | null;
+//# sourceMappingURL=cache-key.d.ts.map

package/dist/server/prebuilt/cache-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/cache-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAsGjE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAM7D;AAsDD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAqCpF;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,aAAa,GACpB,MAAM,GAAG,IAAI,CAkCf"}

package/dist/server/prebuilt/capture-render.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One build-time capture entry (server/prebuilt-builder.ts): render a
+ * registered component in isolation under the synthetic build store and
+ * drain its flight payload under a deadline.
+ */
+import type { CoercedParams } from '../../shared/param-value.ts';
+import type { PrebuiltRegistration } from '../prebuilt-runtime.ts';
+import { type NestedWrapperRender } from './capture-state.ts';
+/** Wrap payload bytes as a single-chunk stream for the smoke revival. */
+export declare function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array>;
+export interface EntryOutcome {
+    bytes: Uint8Array | null;
+    failure: unknown;
+    nested: NestedWrapperRender[];
+    resolvedTags: string[] | undefined;
+    segmentParamsRead: boolean;
+}
+/**
+ * Render one (component, props, coerced-params) entry in isolation and drain
+ * its flight payload. Any `onError` during serialization fails the entry —
+ * a payload with an embedded error row would replay that error on every
+ * future request, so only fully clean renders are captured.
+ */
+export declare function renderEntry(registration: PrebuiltRegistration, props: Record<string, unknown>, coercedParams: CoercedParams, timeoutMs: number, isLayout: boolean): Promise<EntryOutcome>;
+//# sourceMappingURL=capture-render.d.ts.map

package/dist/server/prebuilt/capture-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-render.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/capture-render.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAIjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAKlF,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAO3E;AASD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACnC,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,YAAY,EAAE,oBAAoB,EAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,YAAY,CAAC,CA6DvB"}

package/dist/server/prebuilt/capture-routes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Candidate routes for the post-build capture pass
+ * (server/prebuilt-builder.ts, design/44-render-at-build-time.md §Build
+ * Phase): which pages carry prebuilt components, and which param combos
+ * to capture them for.
+ */
+import type { CoercedParams } from '../../shared/param-value.ts';
+import type { ManifestFile, ManifestSegmentNode } from '../route-matcher.ts';
+export interface CandidateRoute {
+    urlPath: string;
+    page: ManifestFile;
+    /** Layout files along the chain that declare prebuilt components. */
+    layoutsToLoad: ManifestFile[];
+    /** Component IDs attributed to this route's page + layout chain. */
+    componentIds: string[];
+    /** Component IDs from layout files (receive SlotOutlet as children). */
+    layoutComponentIds: Set<string>;
+}
+/**
+ * Walk the manifest tree and collect pages whose file chain (page +
+ * layouts above it) has prebuilt components attributed to it. Slots and
+ * intercepting/private segments are not walked — slot-scoped prebuilt is
+ * already unkeyable at request time when slot params diverge (see
+ * resolveKeyParams in prebuilt-runtime.ts), so the build doesn't model
+ * slots either.
+ */
+export declare function collectCandidateRoutes(root: ManifestSegmentNode, fileComponentMap: Record<string, string[]>): CandidateRoute[];
+export type ParamCombo = CoercedParams;
+/**
+ * Resolve the param combos to capture for a route. Static routes have
+ * exactly one combo (the empty record) — `export const prerender`-style
+ * components on static pages need no enumerator. Dynamic routes require
+ * `generateStaticSegmentParams` (design/44 §generateStaticSegmentParams);
+ * without it every request renders live and the wrapper is a no-op.
+ */
+export declare function enumerateCombos(route: CandidateRoute, pageModule: Record<string, unknown>, log: (message: string) => void): Promise<ParamCombo[] | null>;
+//# sourceMappingURL=capture-routes.d.ts.map

package/dist/server/prebuilt/capture-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-routes.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/capture-routes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAK7E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,YAAY,CAAC;IACnB,qEAAqE;IACrE,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,oEAAoE;IACpE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wEAAwE;IACxE,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,mBAAmB,EACzB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACzC,cAAc,EAAE,CAgClB;AAID,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAmB9B"}

package/dist/server/prebuilt/capture-state.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Capture state — the channel between a payload capture and the
+ * `__prebuilt` wrappers that render inside it (server/prebuilt-runtime.ts).
+ *
+ * Two callers capture a wrapped component's flight payload:
+ *
+ * - **Build time**: the post-build capture pass (server/prebuilt-builder.ts)
+ *   renders each registry entry in turn.
+ * - **Request time**: `captureComponentPayload()` in prebuilt-runtime.ts
+ *   renders a component in isolation for an inline re-render (full miss,
+ *   stale entry, tombstone) or an SWR background re-render. These run
+ *   concurrently with other requests' renders — and with each other.
+ *
+ * During a capture, the component's subtree may render OTHER wrapped
+ * components. Those inner wrappers render live and their output is baked
+ * flat into the outer entry — the nesting clamp of
+ * design/45-cache-lifetimes.md §Nesting Semantics (TIM-1136). The wrapper
+ * reports every render that happens inside a capture:
+ *
+ * - **Cycle**: the inner render IS the entry being captured — same
+ *   component id AND same props key (TIM-1547). Left alone this recurses
+ *   until the render times out; instead the wrapper throws
+ *   `PrebuiltCaptureCycleError`, failing that entry with an error naming
+ *   the cycle (build continues per doc 44 skip-and-report policy; at
+ *   request time the re-render fails and is not cached, and the wrapper
+ *   falls back as for any failed re-render). A component that renders
+ *   itself with different props (a comment thread, a tree) is legitimate
+ *   recursion with a base case and bakes flat like any other nesting.
+ * - **Nesting**: any other wrapper render is recorded per inner component
+ *   with the tags it resolved to. Both capture callers run the clamp rule
+ *   over those records when the entry completes (prebuilt/lifetime.ts).
+ *
+ * Identity is the capture ROOT only. A wrapper cannot see the wrappers
+ * between it and the root: Flight renders a component's children after
+ * the wrapper has returned, in Flight's own async context, not in a frame
+ * the wrapper could enter. So a same-key cycle that closes below the root
+ * (`A(p1) → A(p2) → A(p2) → …`) is not detected here; it is also an
+ * infinite recursion without caching, and the capture's render timeout
+ * fails it.
+ *
+ * The props key is the props half of the cache key (data props only,
+ * framework children outlet stripped — the same inputs the cache key
+ * hashes). The params half is left out: every render inside one capture
+ * reads the same segment params, so props decide identity. Unkeyable props
+ * (live React elements, …) cannot be proven identical and are never a
+ * cycle.
+ *
+ * Each capture's state lives in an AsyncLocalStorage store entered by
+ * `CaptureScope.run()`, so it is visible only to renders started inside
+ * that capture — including work Flight resumes after an await, which runs
+ * in the context the awaited promise was created in. A concurrent request
+ * rendering the same component is not a cycle, and a concurrent request
+ * rendering a different cached component still revives it from cache
+ * instead of baking it live (TIM-1536). Outside any capture
+ * `noteWrapperRender` is a single store lookup.
+ */
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+/** A wrapped component that rendered inside an active capture. */
+export interface NestedWrapperRender {
+    innerId: string;
+    options: PrebuiltComponentOptions;
+    /**
+     * Every tag the inner resolved to across its renders in this capture;
+     * null when its tags function threw (the tags are unknown).
+     */
+    tags: string[] | null;
+}
+/** Per-inner record kept while the capture runs. */
+export interface NestedRecord {
+    options: PrebuiltComponentOptions;
+    tags: Set<string> | null;
+}
+/** Thrown by the wrapper when a capture renders its own entry. */
+export declare class PrebuiltCaptureCycleError extends Error {
+    constructor(componentId: string);
+}
+/** One capture's state, entered for the duration of its render. */
+export interface CaptureScope {
+    /**
+     * Run `fn` inside this capture. Flight renders in the async context it
+     * was started (and pinged) from, so the render must be CREATED inside
+     * `run`; every wrapper it renders then sees this capture.
+     */
+    run<T>(fn: () => T): T;
+    /** Wrapped components that rendered inside this capture so far. */
+    nestedRenders(): NestedWrapperRender[];
+}
+/**
+ * Open a capture of component `outerId` rendered with `props`. Its state
+ * ends with the scope object.
+ */
+export declare function createCaptureScope(outerId: string, options: PrebuiltComponentOptions, props: Record<string, unknown>): CaptureScope;
+/** Whether the current render is inside a capture. */
+export declare function isCaptureActive(): boolean;
+/**
+ * Called by the `__prebuilt` wrapper on every render. No-op outside a
+ * capture. Throws `PrebuiltCaptureCycleError` when the render is the
+ * entry the enclosing capture is producing.
+ */
+export declare function noteWrapperRender(innerId: string, options: PrebuiltComponentOptions, props: Record<string, unknown>): void;
+//# sourceMappingURL=capture-state.d.ts.map

package/dist/server/prebuilt/capture-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-state.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/capture-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAOH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAKvE,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,wBAAwB,CAAC;IAClC;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACvB;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,wBAAwB,CAAC;IAClC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAC1B;AAED,kEAAkE;AAClE,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAY,WAAW,EAAE,MAAM,EAO9B;CACF;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,mEAAmE;IACnE,aAAa,IAAI,mBAAmB,EAAE,CAAC;CACxC;AAoBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,YAAY,CAed;AAED,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CA8BN"}

package/dist/server/prebuilt/key-discipline.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Key-discipline diagnostic for cache.component (design/45 §Enforcement).
+ *
+ * Runtime-tier cached components MAY read request context, but the cache
+ * key is computed from props and segment params only — request-derived
+ * values in cached output are the data-leak danger zone (design/06
+ * security note). During a capture render the ALS store is wrapped in a
+ * transparent observing proxy; any request-context read produces a
+ * structured, rate-limited production diagnostic.
+ *
+ * The diagnostic fires per offending component, rate-limited to once per
+ * interval (default 60 s) — not once per process. This ensures the
+ * signal stays visible in log aggregators across restarts and deploys.
+ *
+ * When `strictKeyDiscipline` is enabled (via timber.config.ts
+ * `cache.strictKeyDiscipline: true`), the diagnostic is promoted to a
+ * thrown error that prevents the tainted payload from being cached.
+ */
+import type { RequestContextStore } from '../als-registry.ts';
+/**
+ * Configure strict key-discipline mode. When true, a violation throws
+ * instead of logging — the tainted payload is never cached.
+ * Called at boot from the RSC entry with the resolved config value.
+ */
+export declare function setKeyDisciplineStrict(enabled: boolean): void;
+/**
+ * Whether the proxy should be created for this component on this render.
+ * Returns true when strict mode is on (always check) or enough time has
+ * elapsed since the last diagnostic for this component.
+ */
+export declare function shouldCheckKeyDiscipline(id: string): boolean;
+/**
+ * Wrap a store with a proxy that records per-request field access.
+ * The proxy forwards all reads/writes transparently — it only observes.
+ */
+export declare function createKeyDisciplineProxy(store: RequestContextStore): {
+    proxy: RequestContextStore;
+    accessedApis: Set<string>;
+};
+/**
+ * Emit the key-discipline diagnostic or throw in strict mode.
+ *
+ * In strict mode: throws an error so the tainted payload is never cached.
+ * In default mode: emits a structured error-level diagnostic through the
+ * logger (same path as render errors), rate-limited per component.
+ */
+export declare function emitKeyDisciplineWarning(id: string, apis: Set<string>): void;
+/**
+ * Reset all diagnostic state. Exported for tests only.
+ */
+export declare function resetKeyDisciplineState(): void;
+//# sourceMappingURL=key-discipline.d.ts.map

package/dist/server/prebuilt/key-discipline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-discipline.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/key-discipline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAiB9D;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,mBAAmB,GAAG;IACpE,KAAK,EAAE,mBAAmB,CAAC;IAC3B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B,CAUA;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CA8B5E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}

package/dist/server/prebuilt/lifetime.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lifetime declarations of a `cache.component` — `prerender`, `ttl`,
+ * `tags` (design/45-cache-lifetimes.md) — and the nesting clamp between
+ * two of them (§Nesting Semantics, TIM-1136).
+ *
+ * The clamp rule lives here once, for both places a capture can embed one
+ * wrapped component in another: the post-build capture pass
+ * (server/prebuilt-builder.ts) and request-time re-renders
+ * (`captureComponentPayload()` in server/prebuilt-runtime.ts, TIM-1545).
+ */
+import type { NestedWrapperRender } from './capture-state.ts';
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+/** Whether the component has a runtime lifetime (ttl or tags). */
+export declare function hasRuntimeLifetime(options: PrebuiltComponentOptions): boolean;
+/**
+ * Resolve tags from options (may be static array or function of props).
+ * Function-form tags receive DATA props only — slot props are excluded so
+ * the tags fn never sees SlotOutlet placeholders (capture paths pass
+ * placeholder-substituted props) and tags stay deterministic per key.
+ */
+export declare function resolveTags(options: PrebuiltComponentOptions, props: Record<string, unknown>): string[];
+/** The entry a capture is producing: its declaration and resolved tags. */
+export interface CapturedLifetime {
+    id: string;
+    options: PrebuiltComponentOptions;
+    tags: readonly string[];
+}
+/**
+ * Warn for each wrapped component embedded in `outer`'s captured payload
+ * whose refresh channels the outer cannot honor. Once per (outer, inner)
+ * pair for the lifetime of `warnedPairs` — the builder passes one per
+ * build, the runtime one per process, since re-renders repeat. The key is
+ * the pair alone, not the reason: resolved tags vary with props, and a key
+ * that included them would grow with the data. So the first clamp found
+ * for a pair is the one reported. Returns the number of warnings emitted.
+ */
+export declare function warnNestingClamps(outer: CapturedLifetime, nested: readonly NestedWrapperRender[], warnedPairs: Set<string>, log: (message: string) => void): number;
+//# sourceMappingURL=lifetime.d.ts.map

package/dist/server/prebuilt/lifetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifetime.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/lifetime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAEvE,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,EAAE,CASV;AAID,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,wBAAwB,CAAC;IAClC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAmDD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC7B,MAAM,CAsCR"}