@timber-js/app 0.2.0-alpha.163 → 0.2.0-alpha.165

package/dist/server/internal.js

@@ -1,8 +1,8 @@
 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, 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-B_O6-mdJ.js";
-import { i as coerce, t as executeAction } from "../_chunks/actions-cjklt63G.js";
-import { a as getManifestEntry, b as wasInvalidatedSince, c as lookupPrebuiltPayload, d as checkVersionSkew, i as storeOverlayEntry, l as setPrebuiltPayloadSource, n as lookupOverlay, o as hasPrebuiltPayloadSource, r as overlayKey, s as isParamIndependent, u as applyReloadHeaders, v as currentInvalidationEpoch, x as createSingleflight, y as lastInvalidationEpochFor } from "../_chunks/cache-api-CzYUlgXA.js";
+import { i as coerce, t as executeAction } from "../_chunks/actions-CSDD6x7U.js";
+import { a as getManifestEntry, b as wasInvalidatedSince, c as lookupPrebuiltPayload, d as checkVersionSkew, i as storeOverlayEntry, l as setPrebuiltPayloadSource, n as lookupOverlay, o as hasPrebuiltPayloadSource, r as overlayKey, s as isParamIndependent, u as applyReloadHeaders, v as currentInvalidationEpoch, x as createSingleflight, y as lastInvalidationEpochFor } from "../_chunks/cache-api-eb1gydM7.js";
 import "../client/error-boundary.js";
 import { n as toBracketKey } from "../_chunks/resolve-schema-3iUvBV5T.js";
 import "../_chunks/segment-context-ZDnXDkbz.js";
@@ -1633,17 +1633,17 @@ async function coerceSegmentParams(match) {
 * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
 */
 var EMPTY_SEGMENT_UPDATES = /* @__PURE__ */ new Map();
-var CTX_KEY$1 = Symbol.for("__timber_segment_update_ctx");
-function getOrCreateContext$1() {
-	const existing = globalThis[CTX_KEY$1];
+var CTX_KEY$2 = Symbol.for("__timber_segment_update_ctx");
+function getOrCreateContext$2() {
+	const existing = globalThis[CTX_KEY$2];
 	if (existing !== void 0) return existing;
 	if (typeof React.createContext === "function") {
 		const ctx = React.createContext(EMPTY_SEGMENT_UPDATES);
-		globalThis[CTX_KEY$1] = ctx;
+		globalThis[CTX_KEY$2] = ctx;
 		return ctx;
 	}
 }
-getOrCreateContext$1();
+getOrCreateContext$2();
 //#endregion
 //#region src/client/segment-outlet.tsx
 /**
@@ -1690,17 +1690,17 @@ getOrCreateContext$1();
 *
 * See design/45-cache-lifetimes.md §Layout Propagation.
 */
-var CTX_KEY = Symbol.for("__timber_child_segment_ctx");
-function getOrCreateContext() {
-	const existing = globalThis[CTX_KEY];
+var CTX_KEY$1 = Symbol.for("__timber_child_segment_ctx");
+function getOrCreateContext$1() {
+	const existing = globalThis[CTX_KEY$1];
 	if (existing !== void 0) return existing;
 	if (typeof React.createContext === "function") {
 		const ctx = React.createContext(null);
-		globalThis[CTX_KEY] = ctx;
+		globalThis[CTX_KEY$1] = ctx;
 		return ctx;
 	}
 }
-var ChildSegmentContext = getOrCreateContext();
+var ChildSegmentContext = getOrCreateContext$1();
 //#endregion
 //#region src/client/child-segment-outlet.tsx
 /**
@@ -2287,7 +2287,7 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 	const responseHeaders = new Headers();
 	const requestHeaderOverlay = new Headers();
 	responseHeaders.set("Cache-Control", "private, no-cache, no-store, max-age=0, must-revalidate");
-	if (config.earlyHints) try {
+	if (config.earlyHints && !isRscRequest) try {
 		await config.earlyHints(match, req, responseHeaders);
 	} catch (err) {
 		swallow(err, "early hints hook threw");
@@ -3195,6 +3195,58 @@ function toUnkeyable(error) {
 	return null;
 }
 /**
+* Split a props record into data props (participate in the cache key) and
+* slot values (React-element holes, excluded from the key) per the
+* component's declared `slots` option (TIM-1173).
+*
+* Every DECLARED slot lands in `slotValues` — present or not — because the
+* capture render always injects a SlotOutlet placeholder for each declared
+* slot: the cached shell is identical whether the caller passed the slot
+* or omitted it, so slot presence must not vary the key. `dataProps` is
+* everything else and is what gets hashed.
+*
+* Returns null when the props OBJECT itself is outside the identity
+* contract at the top level — accessors, symbol-keyed or non-enumerable
+* properties, or a non-`Object.prototype` prototype. Splitting such an
+* object would normalize away observable state (and reading an accessor
+* would invoke user code, which this walk must never do) BEFORE
+* `computeComponentCacheKey` gets the chance to reject it — a cached
+* shell could then be served for inputs a live render distinguishes.
+* Null means unkeyable: the caller renders live with the original props.
+* The walk is descriptor-reads only; getters are never invoked. Nested
+* data-prop values still face the full allowlist when hashed.
+*/
+/** Create an own enumerable data property — safe for keys like `__proto__`. */
+function defineOwn(target, key, value) {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
+function splitSlotProps(props, slots) {
+	try {
+		if (Object.getPrototypeOf(props) !== Object.prototype) return null;
+		if (Object.getOwnPropertySymbols(props).length > 0) return null;
+		const slotSet = new Set(slots);
+		const dataProps = {};
+		const slotValues = {};
+		for (const key of Object.getOwnPropertyNames(props)) {
+			const desc = Object.getOwnPropertyDescriptor(props, key);
+			if (desc === void 0 || desc.get !== void 0 || desc.set !== void 0 || !desc.enumerable) return null;
+			defineOwn(slotSet.has(key) ? slotValues : dataProps, key, desc.value);
+		}
+		for (const slot of slotSet) if (!Object.hasOwn(slotValues, slot)) defineOwn(slotValues, slot, void 0);
+		return {
+			dataProps,
+			slotValues
+		};
+	} catch (error) {
+		return toUnkeyable(error);
+	}
+}
+/**
 * Compute the cache-entry hash for a component render:
 * `sha256({props, params}).slice(0, 16)` over canonical JSON.
 *
@@ -3212,6 +3264,216 @@ function computeComponentCacheKey(props, params) {
 	return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
 }
 //#endregion
+//#region src/client/slot-context.ts
+/**
+* SlotContext — delivers live slot content to SlotOutlet holes inside
+* cached component shells (TIM-1173).
+*
+* A `cache.component(Fn, { slots: [...] })` shell is captured with a
+* stable <SlotOutlet slot={name} /> client reference in place of each
+* declared slot prop. At request time the revived shell is wrapped in a
+* SlotsProvider carrying the live slot values; each outlet reads its
+* value from this context by name.
+*
+* The value is a per-instance record — the NEAREST provider wins, so two
+* instances of the same cached component on one page each resolve their
+* own children, and a slot component nested inside another slot
+* component's children reads its own provider, not the outer one.
+*
+* Generalizes the ChildSegmentContext pattern (TIM-1181) from a single
+* implicit `children` hole on layouts to explicitly declared, named slot
+* props on any cached component.
+*
+* SINGLETON GUARANTEE: globalThis + Symbol.for — the RSC client bundler
+* can duplicate this module across chunks; globalThis guarantees a single
+* context instance. Same pattern as ChildSegmentContext.
+*
+* See design/45-cache-lifetimes.md §Slot Components.
+*/
+var CTX_KEY = Symbol.for("__timber_slot_ctx");
+function getOrCreateContext() {
+	const existing = globalThis[CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+var SlotContext = getOrCreateContext();
+//#endregion
+//#region src/client/slot-outlet.tsx
+/**
+* SlotOutlet — the hole in a cached component shell (TIM-1173).
+*
+* At capture time the prebuilt runtime renders the wrapped component with
+* <SlotOutlet slot={name} /> in place of each declared slot prop. Being a
+* client component, it serializes into the flight payload as a stable,
+* deterministic client reference — the same bytes regardless of what live
+* content will fill the hole. At request time the revived shell sits under
+* a SlotsProvider and each outlet reads its live value from SlotContext.
+*
+* See design/45-cache-lifetimes.md §Slot Components.
+*/
+function SlotOutlet({ slot }) {
+	const values = useContext(SlotContext);
+	return values ? values[slot] ?? null : null;
+}
+//#endregion
+//#region src/client/slot-provider.tsx
+/**
+* SlotsProvider — wraps a revived cached shell to supply live slot content
+* to the SlotOutlet holes inside it (TIM-1173).
+*
+* Tree structure per cached-component instance:
+*   SlotsProvider(values={children: <Live />})
+*     └── revived shell
+*          └── SlotOutlet(slot="children") → reads context → <Live />
+*
+* See design/45-cache-lifetimes.md §Slot Components.
+*/
+function SlotsProvider({ values, children }) {
+	return createElement(SlotContext.Provider, { value: values }, children);
+}
+//#endregion
+//#region src/server/prebuilt/slots.ts
+/**
+* Slot-component helpers for cache.component (TIM-1173).
+*
+* A `slots: ['children', ...]` declaration caches the component's output
+* as a shell with a stable <SlotOutlet slot={name} /> client-reference
+* hole per declared slot prop; live slot content composes in per instance
+* at request time via SlotsProvider/SlotContext. This generalizes the
+* TIM-1181 layout mechanism (ChildSegmentOutlet) to explicitly declared,
+* named slots on any cached component.
+*
+* Both the production wrapper (cache path) and the dev wrapper (no cache,
+* same tree shape for dev/prod parity) build their render from these
+* helpers. See design/45-cache-lifetimes.md §Slot Components.
+*/
+/**
+* Is this value the framework-injected `<ChildSegmentOutlet />` element?
+* Total: the `in` probe and `.type` read run against a user-controlled
+* value, and a Proxy trap can throw — that must classify as "not the
+* outlet" (the canonicalizer then rejects the value as unkeyable → live
+* render), not abort the request (codex P2 on PR #890).
+*/
+function isChildSegmentOutletElement(value) {
+	try {
+		return value != null && typeof value === "object" && "type" in value && value.type === ChildSegmentOutlet;
+	} catch {
+		return false;
+	}
+}
+/**
+* Dense array of non-empty strings — no holes, no non-string entries.
+* Total: the reads run against a user-controlled value at module load,
+* and a throwing Proxy trap must classify as invalid, not crash startup.
+*/
+function isDenseStringArray(value) {
+	try {
+		if (!Array.isArray(value)) return false;
+		for (let i = 0; i < value.length; i++) {
+			if (!Object.hasOwn(value, i)) return false;
+			const entry = value[i];
+			if (typeof entry !== "string" || entry.length === 0) return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate the `slots` option. Both the production and dev wrappers gate
+* on this — slot substitution is active in dev exactly when it would be
+* active in production, so the tree shape a component sees never
+* diverges between the two.
+*/
+function resolveSlotNames(id, options) {
+	const slots = options.slots;
+	if (slots === void 0) return { kind: "none" };
+	if (!isDenseStringArray(slots)) {
+		console.warn(`[timber] cache.component "${id}": invalid slots declaration — expected an array of non-empty prop-name strings. Slot caching is disabled.`);
+		return { kind: "disabled" };
+	}
+	if (slots.length === 0) return { kind: "none" };
+	if (!(options.ttl !== void 0 || options.tags != null)) {
+		console.warn(`[timber] cache.component "${id}": slots require a runtime lifetime (ttl and/or tags). Slot caching is disabled.`);
+		return { kind: "disabled" };
+	}
+	return {
+		kind: "active",
+		slots
+	};
+}
+/**
+* Split the live props into the cacheable shell render (data props plus a
+* deterministic SlotOutlet placeholder per declared slot — identical
+* whether or not the caller passed the slot) and the per-instance live
+* slot values.
+*
+* Null when the props object itself is unkeyable at the top level
+* (accessors, hidden properties, exotic prototype — see splitSlotProps):
+* the caller must render live with the original props.
+*/
+function prepareSlotRender(props, slots) {
+	const split = splitSlotProps(props ?? {}, slots);
+	if (split === null) return null;
+	const { dataProps, slotValues } = split;
+	const shellProps = { ...dataProps };
+	for (const slot of slots) Object.defineProperty(shellProps, slot, {
+		value: createElement(SlotOutlet, { slot }),
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	return {
+		shellProps,
+		dataProps,
+		slotValues
+	};
+}
+/**
+* Wrap a rendered shell (revived payload or live element) in a
+* per-instance SlotsProvider feeding the live values to its outlets.
+*/
+function wrapInSlotsProvider(shell, slotValues) {
+	return createElement(SlotsProvider, {
+		values: slotValues,
+		children: shell
+	});
+}
+//#endregion
+//#region src/server/prebuilt/key-discipline.ts
+/** Components already warned — exported so tests can reset between cases. */
+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.`);
+}
+//#endregion
 //#region src/server/prebuilt/capture-state.ts
 /** Thrown by the wrapper when a capture renders its own component. */
 var PrebuiltCaptureCycleError = class extends Error {
@@ -3343,6 +3605,26 @@ function resolveKeyParams(store) {
 	}
 	return main;
 }
+/**
+* Mirror the production cache-key decision for a slot render, with no
+* cache IO — used by the dev wrapper so slot substitution happens in dev
+* exactly when production would serve the cache path rather than the
+* live fallback (dev/prod parity, codex P2 on PR #890): requires an ALS
+* store, keyable params (slot-param divergence unkeys), and keyable data
+* props (after the ChildSegmentOutlet strip).
+*/
+function isSlotRenderKeyable(dataProps) {
+	const store = requestContextAls.getStore();
+	if (!store) return false;
+	const keyParams = resolveKeyParams(store);
+	if (keyParams === null) return false;
+	let keyProps = dataProps;
+	if (isChildSegmentOutletElement(keyProps.children)) {
+		const { children: _children, ...rest } = keyProps;
+		keyProps = rest;
+	}
+	return computeComponentCacheKey(keyProps, keyParams) !== null;
+}
 /** Wrap payload bytes as a single-chunk ReadableStream for the decoder. */
 function bytesToStream(bytes) {
 	return new ReadableStream({ start(controller) {
@@ -3354,11 +3636,34 @@ function bytesToStream(bytes) {
 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). */
+/**
+* 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.
+*/
 function resolveTags(options, props) {
 	if (!options.tags) return [];
 	if (Array.isArray(options.tags)) return options.tags;
-	return options.tags(props);
+	const slots = options.slots;
+	const fnProps = slots && slots.length > 0 ? splitSlotProps(props, slots)?.dataProps ?? props : props;
+	return options.tags(fnProps);
+}
+/**
+* Serve a slot component from the cache: split live slot values out of the
+* props, look up / capture the shell (data props + a deterministic
+* SlotOutlet placeholder per slot), and wrap the revived shell in a
+* per-instance SlotsProvider that feeds the live values to the outlets.
+*
+* Null on any miss — the caller renders live with the original props.
+*/
+async function tryReviveSlotShell(id, options, slots, props) {
+	const render = prepareSlotRender(props, slots);
+	if (render === null) return null;
+	const { shellProps, dataProps, slotValues } = render;
+	const revived = await tryRevivePayload(id, options, shellProps, dataProps);
+	if (revived === null) return null;
+	return { element: wrapInSlotsProvider(revived.element, slotValues) };
 }
 var rscFns = null;
 function requireRscFunctions() {
@@ -3382,33 +3687,6 @@ async function revivePayload(id, payload, outcome) {
 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.
@@ -3539,7 +3817,7 @@ function backgroundRerender(id, component, props, cacheKey, options, hasSeed, sn
 *
 * Null on any miss — the caller renders live.
 */
-async function tryRevivePayload(id, options, props) {
+async function tryRevivePayload(id, options, props, keyPropsOverride) {
 	const hasSource = hasPrebuiltPayloadSource();
 	const hasRuntime = hasRuntimeLifetime(options);
 	if (!hasSource && !hasRuntime) return null;
@@ -3547,13 +3825,11 @@ async function tryRevivePayload(id, options, props) {
 	if (!store) return null;
 	const keyParams = (options.prerender ? await isParamIndependent(id) : false) ? {} : resolveKeyParams(store);
 	if (keyParams === null) return null;
-	const allProps = props ?? {};
-	let keyProps;
-	const childrenValue = allProps.children;
-	if (childrenValue != null && typeof childrenValue === "object" && "type" in childrenValue && childrenValue.type === ChildSegmentOutlet) {
-		const { children: _children, ...rest } = allProps;
+	let keyProps = keyPropsOverride ?? props ?? {};
+	if (isChildSegmentOutletElement(keyProps.children)) {
+		const { children: _children, ...rest } = keyProps;
 		keyProps = rest;
-	} else keyProps = allProps;
+	}
 	const cacheKey = computeComponentCacheKey(keyProps, keyParams);
 	if (cacheKey === null) return null;
 	const outcome = options.fallbackOnMissingSegmentParams === false ? "failing the render (fallbackOnMissingSegmentParams: false)" : "rendering dynamically";
@@ -3605,6 +3881,19 @@ async function tryRevivePayload(id, options, props) {
 * component live (miss).
 */
 function __prebuilt(id, component, options = {}) {
+	const resolution = resolveSlotNames(id, options);
+	const slots = resolution.kind === "active" ? resolution.slots : null;
+	if (resolution.kind === "active" && options.prerender) {
+		console.warn(`[timber] cache.component "${id}": slots are runtime-tier only — prerender is ignored (the build cannot enumerate slot content). Use ttl/tags for the cache lifetime.`);
+		options = {
+			...options,
+			prerender: void 0
+		};
+	}
+	if (resolution.kind === "disabled") options = {
+		...options,
+		slots: void 0
+	};
 	registry.set(id, {
 		id,
 		component,
@@ -3613,7 +3902,7 @@ function __prebuilt(id, component, options = {}) {
 	const wrapper = async (props) => {
 		noteWrapperRender(id, options);
 		if (isCaptureActive()) return createElement(component, props);
-		const revived = await tryRevivePayload(id, options, props);
+		const revived = slots ? await tryReviveSlotShell(id, options, slots, props) : 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);
@@ -3635,13 +3924,19 @@ function getPrebuiltRegistry() {
 * component on first render so the production behavior difference is visible.
 * See design/44 §Dev Mode.
 */
-function __prebuiltDev(name, component, _options) {
+function __prebuiltDev(name, component, options = {}) {
+	const resolution = resolveSlotNames(name, options);
+	const slots = resolution.kind === "active" ? resolution.slots : null;
 	let logged = false;
 	const wrapper = (props) => {
 		if (!logged) {
 			logged = true;
 			console.log(`[timber] cache.component: "${name}" — rendering dynamically (dev mode)`);
 		}
+		if (slots) {
+			const render = prepareSlotRender(props, slots);
+			if (render !== null && isSlotRenderKeyable(render.dataProps)) return wrapInSlotsProvider(createElement(component, render.shellProps), render.slotValues);
+		}
 		return createElement(component, props);
 	};
 	return wrapper;