@timber-js/app 0.2.0-alpha.157 → 0.2.0-alpha.159

package/dist/server/internal.js

@@ -1,12 +1,13 @@
 import { a as classifyMetadataRoute, i as METADATA_ROUTE_CONVENTIONS, o as getMetadataRouteAutoLink, r as canonicalize, s as getMetadataRouteServePath } from "../_chunks/canonicalize-P41GR6tY.js";
 import { n as classifyUrlSegment } from "../_chunks/segment-classify-CDDRVKs7.js";
-import { A as runWithRequestContext, D as getSearchParams, G as getTraceId, H as generateTraceId, I as getSetCookieHeaders, J as setSpanAttribute, K as replaceTraceId, M as setMutableCookieContext, N as setSegmentParams, O as getSegmentParams, P as getCookie, Q as requestContextAls, R as isDebug, T as getHeader, U as getOtelTraceId, X as earlyHintsSenderAls, Y as withSpan, _ as RedirectSignal, a as logProxyError, c as logRequestReceived, d as logSwrRefetchFailed, et as timingAls, f as logWaitUntilRejected, g as DenySignal, h as swallow, i as logMiddlewareShortCircuit, j as setMatchedSegmentPath, k as markResponseFlushed, l as logRouteError, m as setLogger, n as logCacheMiss, o as logRenderError, p as logWaitUntilUnsupported, q as runWithTraceId, r as logMiddlewareError, s as logRequestCompleted, t as getLogger, u as logSlowRequest, v as RenderError, w as applyRequestHeaderOverlay } from "../_chunks/logger-C5v1IMuh.js";
-import { i as coerce, t as executeAction } from "../_chunks/actions-CqE7SW7E.js";
+import { A as runWithRequestContext, D as getSearchParams, G as getTraceId, H as generateTraceId, I as getSetCookieHeaders, J as setSpanAttribute, K as replaceTraceId, L as getWaitUntil, M as setMutableCookieContext, N as setSegmentParams, O as getSegmentParams, P as getCookie, Q as requestContextAls, R as isDebug, T as getHeader, U as getOtelTraceId, X as earlyHintsSenderAls, Y as withSpan, _ as RedirectSignal, a as logProxyError, c as logRequestReceived, d as logSwrRefetchFailed, et as timingAls, f as logWaitUntilRejected, g as DenySignal, h as swallow, i as logMiddlewareShortCircuit, j as setMatchedSegmentPath, k as markResponseFlushed, l as logRouteError, m as setLogger, n as logCacheMiss, o as logRenderError, p as logWaitUntilUnsupported, q as runWithTraceId, r as logMiddlewareError, s as logRequestCompleted, t as getLogger, u as logSlowRequest, v as RenderError, w as applyRequestHeaderOverlay } from "../_chunks/logger-CrRmZMlo.js";
+import { i as coerce, t as executeAction } from "../_chunks/actions-CBbP1hHO.js";
+import { _ as currentInvalidationEpoch, a as getManifestEntry, b as createSingleflight, c as setPrebuiltPayloadSource, i as storeOverlayEntry, l as applyReloadHeaders, n as lookupOverlay, o as hasPrebuiltPayloadSource, r as overlayKey, s as lookupPrebuiltPayload, u as checkVersionSkew, v as lastInvalidationEpochFor, y as wasInvalidatedSince } from "../_chunks/cache-api-DsWEYwVZ.js";
 import "../client/error-boundary.js";
 import { n as toBracketKey } from "../_chunks/resolve-schema-3iUvBV5T.js";
 import "../_chunks/segment-context-ZDnXDkbz.js";
 import { readFile } from "node:fs/promises";
-import "node:crypto";
+import { createHash } from "node:crypto";
 import React, { createElement } from "react";
 //#region src/server/server-timing.ts
 /**
@@ -1681,76 +1682,6 @@ var ParamCoercionError = class extends Error {
 	}
 };
 //#endregion
-//#region src/server/version-skew.ts
-/**
-* Version Skew Detection — graceful recovery when stale clients hit new deployments.
-*
-* When a new version of the app is deployed, clients with open tabs still have
-* the old JavaScript bundle. Without version skew handling, these stale clients
-* will experience:
-*
-* 1. Server action calls that crash (action IDs are content-hashed)
-* 2. Chunk load failures (old filenames gone from CDN)
-* 3. RSC payload mismatches (component references differ between builds)
-*
-* This module implements deployment ID comparison:
-* - A per-build deployment ID is generated at build time (see build-manifest.ts)
-* - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
-* - The server compares it against the current build's ID
-* - On mismatch: signal the client to reload (not crash)
-*
-* The deployment ID is always-on in production. Dev mode skips the check
-* (HMR handles code updates without full reloads).
-*
-* See design/25-production-deployments.md, TIM-446
-*/
-/** Header sent by the client with every RSC/action request. */
-var DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
-/** Response header that signals the client to do a full page reload. */
-var RELOAD_HEADER = "X-Timber-Reload";
-/**
-* The current build's deployment ID. Set at startup from the manifest init
-* module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
-*/
-var currentDeploymentId = null;
-/**
-* Check if a request's deployment ID matches the current build.
-*
-* Returns `{ ok: true }` when:
-* - Dev mode (no deployment ID set — HMR handles updates)
-* - No deployment ID header (initial page load, non-RSC request)
-* - Deployment IDs match
-*
-* Returns `{ ok: false }` when:
-* - Client sends a deployment ID that differs from the current build
-*/
-function checkVersionSkew(req) {
-	if (!currentDeploymentId) return {
-		ok: true,
-		clientId: null
-	};
-	const clientId = req.headers.get(DEPLOYMENT_ID_HEADER);
-	if (!clientId) return {
-		ok: true,
-		clientId: null
-	};
-	if (clientId === currentDeploymentId) return {
-		ok: true,
-		clientId
-	};
-	return {
-		ok: false,
-		clientId
-	};
-}
-/**
-* Apply version skew reload headers to a response.
-* Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
-*/
-function applyReloadHeaders(headers) {
-	headers.set(RELOAD_HEADER, "1");
-}
-//#endregion
 //#region src/server/pipeline-metadata.ts
 /**
 * Metadata route helpers for the request pipeline.
@@ -3083,6 +3014,564 @@ var RenderTimeoutError = class extends Error {
 	}
 };
 //#endregion
-export { AccessGate, DEFAULT_LIMITS, DenySignal, METADATA_ROUTE_CONVENTIONS, RedirectSignal, RenderError, RenderTimeoutError, SlotAccessGate, buildElementTree, callOnRequestError, canonicalize, classifyMetadataRoute, coerce, collectEarlyHintHeaders, createPipeline, enforceBodyLimits, executeAction, formatLinkHeader, generateTraceId, getCookie, getHeader, getLogger, getMetadataRouteAutoLink, getMetadataRouteServePath, getSearchParams, getSegmentParams, getSetCookieHeaders, handleRouteRequest, hasOnRequestError, loadInstrumentation, logCacheMiss, logMiddlewareError, logMiddlewareShortCircuit, logProxyError, logRenderError, logRequestCompleted, logRequestReceived, logSlowRequest, logSwrRefetchFailed, logWaitUntilRejected, logWaitUntilUnsupported, markResponseFlushed, parseBodySize, renderMetadataToElements, replaceTraceId, resolveAllowedMethods, resolveMetadata, resolveMetadataUrls, resolveSlotDenied, resolveStatusFile, resolveTitle, runMiddleware, runProxy, runWithEarlyHintsSender, runWithRequestContext, runWithTraceId, sendEarlyHints103, setLogger, setMutableCookieContext, setSegmentParams, validateCsrf };
+//#region src/server/prebuilt/cache-key.ts
+/**
+* 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).
+*/
+var UnkeyableValueError = class extends Error {};
+function canonicalize$1(value, seen) {
+	if (value === null) return "null";
+	switch (typeof value) {
+		case "string": return JSON.stringify(value);
+		case "boolean": return value ? "true" : "false";
+		case "number":
+			if (!Number.isFinite(value)) throw new UnkeyableValueError("non-finite number");
+			return Object.is(value, -0) ? "-0" : String(value);
+		case "object": break;
+		case "undefined": return "undefined";
+		default: throw new UnkeyableValueError(`unsupported type: ${typeof value}`);
+	}
+	const obj = value;
+	if (seen.has(obj)) throw new UnkeyableValueError("repeated object reference (cycle or alias)");
+	seen.add(obj);
+	if (Object.getOwnPropertySymbols(obj).length > 0) throw new UnkeyableValueError("symbol-keyed property");
+	{
+		if (Array.isArray(obj)) {
+			if (Object.getOwnPropertyNames(obj).length !== obj.length + 1) throw new UnkeyableValueError("non-index array property");
+			const parts = [];
+			for (let i = 0; i < obj.length; i++) {
+				const desc = Object.getOwnPropertyDescriptor(obj, i);
+				if (desc === void 0) throw new UnkeyableValueError("sparse array hole");
+				if (desc.get !== void 0 || desc.set !== void 0) throw new UnkeyableValueError("accessor property");
+				if (!desc.enumerable) throw new UnkeyableValueError("non-enumerable array element");
+				parts.push(canonicalize$1(desc.value, seen));
+			}
+			return "[" + parts.join(",") + "]";
+		}
+		if (Object.getPrototypeOf(obj) !== Object.prototype) throw new UnkeyableValueError("non-plain object");
+		const keys = Object.keys(obj).sort();
+		if (keys.length !== Object.getOwnPropertyNames(obj).length) throw new UnkeyableValueError("non-enumerable property");
+		const parts = [];
+		for (const key of keys) {
+			const desc = Object.getOwnPropertyDescriptor(obj, key);
+			if (desc.get !== void 0 || desc.set !== void 0) throw new UnkeyableValueError("accessor property");
+			parts.push(JSON.stringify(key) + ":" + canonicalize$1(desc.value, seen));
+		}
+		return "{" + parts.join(",") + "}";
+	}
+}
+/**
+* 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.
+*/
+function tryCanonicalize(value) {
+	try {
+		return canonicalize$1(value, /* @__PURE__ */ new Set());
+	} catch (error) {
+		return toUnkeyable(error);
+	}
+}
+/**
+* Totality by construction: ANY throw from the walk means the input is
+* outside the keyable domain. The walk touches only user-controlled
+* values through reflection ops — and a Proxy trap can throw arbitrary
+* errors from any of them (codex review on PR #835) — so converting only
+* UnkeyableValueError would let hostile/exotic inputs abort a render
+* that plain live rendering would have served fine. Unexpected error
+* types are logged for visibility (they would indicate either a proxy
+* trap or a canonicalizer bug) but still degrade to unkeyable.
+*/
+function toUnkeyable(error) {
+	if (!(error instanceof UnkeyableValueError)) console.error("[timber] cache key canonicalization threw — treating input as unkeyable:", error);
+	return 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.
+*/
+function computeComponentCacheKey(props, params) {
+	let canonical;
+	try {
+		const seen = /* @__PURE__ */ new Set();
+		canonical = "{\"params\":" + canonicalize$1({ ...params }, seen) + ",\"props\":" + canonicalize$1(props, seen) + "}";
+	} catch (error) {
+		return toUnkeyable(error);
+	}
+	return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+//#endregion
+//#region src/server/prebuilt/capture-state.ts
+/** Thrown by the wrapper when a capture renders its own component. */
+var PrebuiltCaptureCycleError = class extends Error {
+	constructor(componentId) {
+		super(`[timber] cache.component "${componentId}" renders itself (directly or through other components) — prerendering it would recurse forever. Remove the cycle or drop { prerender: true } on this component.`);
+		this.name = "PrebuiltCaptureCycleError";
+	}
+};
+var active = null;
+/**
+* Mark a capture as active. The builder calls this immediately before
+* rendering an entry and MUST pair it with `endCapture()` in a finally.
+*/
+function beginCapture(outerId) {
+	active = {
+		outerId,
+		nested: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* End the active capture and return the wrapped components that rendered
+* inside it (first options object wins per inner ID).
+*/
+function endCapture() {
+	const nested = active?.nested;
+	active = null;
+	if (!nested) return [];
+	return Array.from(nested, ([innerId, options]) => ({
+		innerId,
+		options
+	}));
+}
+/** Whether a build-time capture is currently rendering. */
+function isCaptureActive() {
+	return active !== null;
+}
+/**
+* Called by the `__prebuilt` wrapper on every render. No-op unless a
+* capture is active. Throws `PrebuiltCaptureCycleError` when the wrapper
+* belongs to the component currently being captured.
+*/
+function noteWrapperRender(innerId, options) {
+	if (active === null) return;
+	if (innerId === active.outerId) throw new PrebuiltCaptureCycleError(innerId);
+	if (!active.nested.has(innerId)) active.nested.set(innerId, options);
+}
+//#endregion
+//#region src/server/prebuilt-runtime.ts
+/**
+* Prebuilt component runtime — registration target for the timber-prebuilt
+* transform (plugins/prebuilt.ts) and the request-time half of
+* cache.component (TIM-1140).
+*
+* `cache.component(fn, opts)` call sites are rewritten at build time to
+* `__prebuilt(stableId, fn, opts)` (production) or `__prebuiltDev(name, fn)`
+* (dev). Both are exported via #server-internal — they are framework
+* plumbing, never called by user code directly.
+*
+* Cache hits are served by FLIGHT REVIVAL: the cached `.flight` payload is
+* decoded back into React elements inside the RSC environment with
+* `createFromReadableStream` (the flight client running in the flight
+* server — plugin-rsc wires the server-decode manifest so client
+* references revive as re-serializable reference proxies). The revived
+* element is returned from the wrapper and the outer render re-serializes
+* it like any other subtree. This is the same mechanism as Next.js
+* `"use cache"` (next/src/server/use-cache/use-cache-wrapper.ts).
+*
+* What a hit skips: all user work — data fetching, MDX compilation, the
+* component function itself never runs. What it re-pays: React
+* re-serializes the already-resolved tree (cost proportional to payload
+* size, not to data latency). The alternative — splicing raw payload bytes
+* into the outer stream — avoids re-serialization but requires byte-level
+* coupling to the flight wire format (row framing, ID rebasing, marker
+* detection); it was implemented and reviewed on PR #835 and deliberately
+* replaced by revival. See design/44-render-at-build-time.md
+* §Request-Time Injection.
+*
+* Misses render the original component live via the wrapper's own closure,
+* inside the React pass — segment params from ALS, deny()/redirect()
+* signals, Suspense, and error boundaries behave exactly as an unwrapped
+* component. `fallbackOnMissingSegmentParams: false` throws instead.
+*/
+/** Default timeout for component re-renders (overridden by renderTimeoutMs). */
+var DEFAULT_COMPONENT_TIMEOUT_MS = 3e4;
+/** Singleflight for component re-renders (inline and background). */
+var componentSingleflight = createSingleflight({ timeoutMs: DEFAULT_COMPONENT_TIMEOUT_MS });
+var componentTimeoutMs = DEFAULT_COMPONENT_TIMEOUT_MS;
+var warnedNoWaitUntil = false;
+/**
+* Server-side component registry, keyed by stable component ID. Populated at
+* module load time by `__prebuilt` calls; consumed by the post-build capture
+* pass (TIM-1119). Never serialized — component functions are not
+* Flight-serializable.
+*/
+var registry = /* @__PURE__ */ new Map();
+/**
+* Resolve the params the cache key may faithfully hash, or null if this
+* render is unkeyable.
+*
+* A wrapper rendered inside a parallel slot reads params merged with that
+* slot's overrides (`getSegmentParams`: `{...segmentParams, ...slotParams}`)
+* — but the cache key hashes only the route-level params, and the wrapper
+* cannot know which slot it renders under. The route params are usable
+* only when every slot's merged view canonicalizes identically to them;
+* otherwise two renders with the same key could see different effective
+* inputs and a hit could serve the WRONG cached subtree — so the render
+* goes live: slower, never wrong. (Build-time capture doesn't model slot
+* params either, so a divergent request could never have a faithful
+* entry. Codex review on PR #835; revisit with segment-path-scoped keys
+* if slot-scoped prebuilt is ever needed.)
+*
+* Comparison happens through `tryCanonicalize` — the same single
+* definition of value equality the cache key uses — so anything it
+* cannot represent faithfully (bigint-coerced codec params, accessors,
+* aliases, …) is unkeyable here too, and this guard can never throw.
+*/
+function resolveKeyParams(store) {
+	const main = store.segmentParams ?? {};
+	const map = store.slotParamsMap;
+	if (!map || map.size === 0) return main;
+	const mainCanonical = tryCanonicalize({ ...main });
+	if (mainCanonical === null) return null;
+	for (const slotParams of map.values()) {
+		const merged = tryCanonicalize({
+			...main,
+			...slotParams
+		});
+		if (merged === null || merged !== mainCanonical) return null;
+	}
+	return main;
+}
+/** Wrap payload bytes as a single-chunk ReadableStream for the decoder. */
+function bytesToStream(bytes) {
+	return new ReadableStream({ start(controller) {
+		controller.enqueue(bytes);
+		controller.close();
+	} });
+}
+/** Whether the component has a runtime lifetime (ttl or tags). */
+function hasRuntimeLifetime(options) {
+	return options.ttl !== void 0 || options.tags !== void 0 && options.tags !== null;
+}
+/** Resolve tags from options (may be static array or function of props). */
+function resolveTags(options, props) {
+	if (!options.tags) return [];
+	if (Array.isArray(options.tags)) return options.tags;
+	return options.tags(props);
+}
+var rscFns = null;
+function requireRscFunctions() {
+	if (!rscFns) throw new Error("[timber] RSC functions not wired — setRscFunctions() must be called at boot");
+	return rscFns;
+}
+/**
+* Revive flight payload bytes into a React element.
+* Returns null on any failure (corrupt payload, missing decoder).
+*/
+async function revivePayload(id, payload, outcome) {
+	try {
+		const { createFromReadableStream } = requireRscFunctions();
+		return { element: await createFromReadableStream(bytesToStream(payload)) };
+	} catch (error) {
+		console.error(`[timber] failed to revive prebuilt payload for "${id}" — ${outcome}:`, error);
+		return null;
+	}
+}
+/** Ceiling on component re-render capture (design/13 A2). Uses configured renderTimeoutMs. */
+function getCaptureTimeoutMs() {
+	return componentTimeoutMs;
+}
+var keyDisciplineWarned = /* @__PURE__ */ new Set();
+var REQUEST_CONTEXT_FIELDS = {
+	headers: "headers()",
+	parsedCookies: "cookies()",
+	searchParams: "searchParams"
+};
+/**
+* Wrap a store with a proxy that records per-request field access.
+* The proxy forwards all reads/writes transparently — it only observes.
+*/
+function createKeyDisciplineProxy(store) {
+	const accessedApis = /* @__PURE__ */ new Set();
+	return {
+		proxy: new Proxy(store, { get(target, prop, receiver) {
+			const api = REQUEST_CONTEXT_FIELDS[prop];
+			if (api) accessedApis.add(api);
+			return Reflect.get(target, prop, receiver);
+		} }),
+		accessedApis
+	};
+}
+function emitKeyDisciplineWarning(id, apis) {
+	if (keyDisciplineWarned.has(id)) return;
+	keyDisciplineWarned.add(id);
+	const apiList = Array.from(apis).join(", ");
+	console.warn(`[timber] cache.component key-discipline warning: "${id}" reads ${apiList} but the cache key is computed from props and segment params only. If the output varies by ${apiList}, different users may see each other's cached content. Either pass request-derived values as props (included in the cache key) or remove the ${apiList} call.`);
+}
+/**
+* Render a component in isolation and capture its flight payload bytes.
+* Used for inline re-renders (tombstone/miss) and SWR background re-renders.
+*
+* The stream read is timeout-guarded and the reader is cancelled on
+* expiry (design/13 A2, A3).
+*/
+async function captureComponentPayload(id, component, props) {
+	const { renderToReadableStream } = requireRscFunctions();
+	const element = createElement(component, props);
+	let renderErrored = false;
+	const store = requestContextAls.getStore();
+	const discipline = store && !keyDisciplineWarned.has(id) ? createKeyDisciplineProxy(store) : null;
+	const doCapture = async () => {
+		beginCapture(id);
+		try {
+			const reader = renderToReadableStream(element, { onError() {
+				renderErrored = true;
+				return "";
+			} }).getReader();
+			const chunks = [];
+			let totalLength = 0;
+			const deadline = Date.now() + getCaptureTimeoutMs();
+			try {
+				for (;;) {
+					const remaining = deadline - Date.now();
+					if (remaining <= 0) throw new Error(`[timber] component re-render capture exceeded ${getCaptureTimeoutMs()}ms`);
+					let timer;
+					const { done, value } = await Promise.race([reader.read(), new Promise((_, reject) => {
+						timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`[timber] component re-render stream read timed out`)), remaining);
+					})]);
+					clearTimeout(timer);
+					if (done) break;
+					chunks.push(value);
+					totalLength += value.byteLength;
+				}
+			} finally {
+				reader.cancel().catch(() => {});
+			}
+			if (renderErrored) throw new Error("[timber] component re-render produced error rows — not caching");
+			const result = new Uint8Array(totalLength);
+			let offset = 0;
+			for (const chunk of chunks) {
+				result.set(chunk, offset);
+				offset += chunk.byteLength;
+			}
+			return result;
+		} finally {
+			endCapture();
+		}
+	};
+	const bytes = discipline ? await requestContextAls.run(discipline.proxy, doCapture) : await doCapture();
+	if (discipline && discipline.accessedApis.size > 0) emitKeyDisciplineWarning(id, discipline.accessedApis);
+	return bytes;
+}
+/**
+* Inline re-render: capture flight bytes, store in overlay, revive for
+* the current request. Singleflight-coalesced by overlay key.
+*/
+async function inlineRerender(id, component, props, cacheKey, options, hasSeed, outcome) {
+	const tags = resolveTags(options, props);
+	const oKey = overlayKey(id, cacheKey);
+	const sfKey = `prebuilt:${id}:${cacheKey}\0${lastInvalidationEpochFor(oKey, tags)}`;
+	try {
+		return await revivePayload(id, await componentSingleflight.do(sfKey, async (signal) => {
+			const startEpoch = currentInvalidationEpoch();
+			const bytes = await captureComponentPayload(id, component, props);
+			if (!signal.aborted && hasRuntimeLifetime(options) && !wasInvalidatedSince(startEpoch, oKey, tags)) await storeOverlayEntry(id, cacheKey, bytes, {
+				ttl: options.ttl,
+				tags,
+				hasSeed
+			});
+			return bytes;
+		}), outcome);
+	} catch (error) {
+		console.error(`[timber] cache.component re-render failed for "${id}" — ${outcome}:`, error);
+		return null;
+	}
+}
+/**
+* Snapshot the request context values needed for a background re-render.
+* Creates a FRESH store with copied values — the original ALS store is
+* not referenced after capture.
+*/
+function snapshotRequestContext(store) {
+	return {
+		headers: new Headers(store.headers),
+		originalHeaders: new Headers(store.originalHeaders),
+		cookieHeader: store.cookieHeader,
+		parsedCookies: store.parsedCookies ? new Map(store.parsedCookies) : void 0,
+		searchParams: new URLSearchParams(store.searchParams),
+		searchString: store.searchString,
+		segmentParams: store.segmentParams ? { ...store.segmentParams } : void 0,
+		cookieJar: /* @__PURE__ */ new Map(),
+		flushed: false,
+		mutableContext: false
+	};
+}
+/**
+* Kick off a background re-render via waitUntil. The re-render runs inside
+* a fresh ALS scope with snapshotted request context.
+*/
+function backgroundRerender(id, component, props, cacheKey, options, hasSeed, snapshot) {
+	const waitUntil = getWaitUntil();
+	const tags = resolveTags(options, props);
+	const oKey = overlayKey(id, cacheKey);
+	const startEpoch = currentInvalidationEpoch();
+	const sfKey = `prebuilt-bg:${id}:${cacheKey}\0${lastInvalidationEpochFor(oKey, tags)}`;
+	const work = requestContextAls.run(snapshot, () => componentSingleflight.do(sfKey, async (signal) => {
+		const bytes = await captureComponentPayload(id, component, props);
+		if (!signal.aborted && !wasInvalidatedSince(startEpoch, oKey, tags)) await storeOverlayEntry(id, cacheKey, bytes, {
+			ttl: options.ttl,
+			tags,
+			hasSeed
+		});
+	}).catch((error) => {
+		console.error(`[timber] cache.component background re-render failed for "${id}":`, error);
+	}));
+	if (waitUntil) waitUntil(work);
+	else if (!warnedNoWaitUntil) {
+		warnedNoWaitUntil = true;
+		console.warn("[timber] cache.component SWR background re-render has no waitUntil — the re-render may be killed when the handler returns on serverless platforms. Ensure the adapter wires runWithWaitUntil().");
+	}
+}
+/**
+* Try to serve this render from the prebuilt cache: overlay → artifact →
+* live render. Handles ISR (SWR, tombstones, re-renders) per design/45.
+*
+* Null on any miss — the caller renders live.
+*/
+async function tryRevivePayload(id, options, props) {
+	const hasSource = hasPrebuiltPayloadSource();
+	const hasRuntime = hasRuntimeLifetime(options);
+	if (!hasSource && !hasRuntime) return null;
+	const store = requestContextAls.getStore();
+	if (!store) return null;
+	const keyParams = resolveKeyParams(store);
+	if (keyParams === null) return null;
+	const cacheKey = computeComponentCacheKey(props ?? {}, keyParams);
+	if (cacheKey === null) return null;
+	const outcome = options.fallbackOnMissingSegmentParams === false ? "failing the render (fallbackOnMissingSegmentParams: false)" : "rendering dynamically";
+	const component = registry.get(id)?.component;
+	if (hasRuntime) {
+		const overlayResult = await lookupOverlay(id, cacheKey);
+		if (overlayResult) {
+			const overlayHasSeed = overlayResult.record?.s ?? false;
+			if (overlayResult.kind === "tombstone") {
+				if (component) return await inlineRerender(id, component, props, cacheKey, options, true, outcome);
+				return null;
+			}
+			if (overlayResult.kind === "fresh" && overlayResult.payload) return await revivePayload(id, overlayResult.payload, outcome);
+			if (overlayResult.kind === "stale" && overlayResult.payload) {
+				if (options.staleWhileRevalidate && component) {
+					backgroundRerender(id, component, props, cacheKey, options, overlayHasSeed, snapshotRequestContext(store));
+					return await revivePayload(id, overlayResult.payload, outcome);
+				}
+				if (component) return await inlineRerender(id, component, props, cacheKey, options, overlayHasSeed, outcome);
+				return null;
+			}
+		}
+	}
+	if (hasSource) {
+		const artifactPayload = await lookupPrebuiltPayload(id, cacheKey);
+		if (artifactPayload !== null) {
+			if (options.ttl !== void 0) {
+				const buildTs = (await getManifestEntry(id, cacheKey))?.buildTimestamp ?? 0;
+				if ((Date.now() - buildTs) / 1e3 > options.ttl) {
+					if (options.staleWhileRevalidate && component) {
+						backgroundRerender(id, component, props, cacheKey, options, true, snapshotRequestContext(store));
+						return await revivePayload(id, artifactPayload, outcome);
+					}
+					if (component) return await inlineRerender(id, component, props, cacheKey, options, true, outcome);
+					return null;
+				}
+			}
+			return await revivePayload(id, artifactPayload, outcome);
+		}
+		if (options.prerender) console.warn(`[timber] cache.component cache miss: "${id}" with params ${JSON.stringify(store.segmentParams ?? {})} — ${outcome}`);
+	}
+	if (hasRuntime && component && options.fallbackOnMissingSegmentParams !== false) return await inlineRerender(id, component, props, cacheKey, options, false, outcome);
+	return null;
+}
+/**
+* Production wrapper injected by the timber-prebuilt transform. Registers
+* the component under its stable ID and returns a wrapper component that
+* either revives the cached payload (hit) or renders the original
+* component live (miss).
+*/
+function __prebuilt(id, component, options = {}) {
+	registry.set(id, {
+		id,
+		component,
+		options
+	});
+	const wrapper = async (props) => {
+		noteWrapperRender(id, options);
+		if (isCaptureActive()) return createElement(component, props);
+		const revived = await tryRevivePayload(id, options, props);
+		if (revived !== null) return revived.element;
+		if (options.fallbackOnMissingSegmentParams === false) throw new Error(`[timber] cache.component "${id}": no prebuilt payload for the current params and fallbackOnMissingSegmentParams is false`);
+		return createElement(component, props);
+	};
+	Object.defineProperty(wrapper, "name", { value: `Prebuilt(${id})` });
+	return wrapper;
+}
+/** Look up a registration by stable component ID. */
+function getPrebuiltRegistration(id) {
+	return registry.get(id);
+}
+/** All registrations, for the post-build capture pass (TIM-1119). */
+function getPrebuiltRegistry() {
+	return registry;
+}
+/**
+* Dev-mode wrapper injected by the timber-prebuilt transform: a no-op that
+* renders the component dynamically on every request, logging once per
+* component on first render so the production behavior difference is visible.
+* See design/44 §Dev Mode.
+*/
+function __prebuiltDev(name, component, _options) {
+	let logged = false;
+	const wrapper = (props) => {
+		if (!logged) {
+			logged = true;
+			console.log(`[timber] cache.component: "${name}" — rendering dynamically (dev mode)`);
+		}
+		return createElement(component, props);
+	};
+	return wrapper;
+}
+//#endregion
+export { AccessGate, DEFAULT_LIMITS, DenySignal, METADATA_ROUTE_CONVENTIONS, RedirectSignal, RenderError, RenderTimeoutError, SlotAccessGate, __prebuilt, __prebuiltDev, buildElementTree, callOnRequestError, canonicalize, classifyMetadataRoute, coerce, collectEarlyHintHeaders, computeComponentCacheKey, createPipeline, enforceBodyLimits, executeAction, formatLinkHeader, generateTraceId, getCookie, getHeader, getLogger, getMetadataRouteAutoLink, getMetadataRouteServePath, getPrebuiltRegistration, getPrebuiltRegistry, getSearchParams, getSegmentParams, getSetCookieHeaders, handleRouteRequest, hasOnRequestError, hasPrebuiltPayloadSource, loadInstrumentation, logCacheMiss, logMiddlewareError, logMiddlewareShortCircuit, logProxyError, logRenderError, logRequestCompleted, logRequestReceived, logSlowRequest, logSwrRefetchFailed, logWaitUntilRejected, logWaitUntilUnsupported, markResponseFlushed, parseBodySize, renderMetadataToElements, replaceTraceId, resolveAllowedMethods, resolveMetadata, resolveMetadataUrls, resolveSlotDenied, resolveStatusFile, resolveTitle, runMiddleware, runProxy, runWithEarlyHintsSender, runWithRequestContext, runWithTraceId, sendEarlyHints103, setLogger, setMutableCookieContext, setPrebuiltPayloadSource, setSegmentParams, validateCsrf };
 
 //# sourceMappingURL=internal.js.map