@timber-js/app 0.1.52 → 0.1.54

package/dist/client/index.js

@@ -3,7 +3,7 @@ import { a as _setCurrentParams, c as cachedSearchParams, i as _setCachedSearch,
 import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-DAhgj8Gx.js";
 import { t as useCookie } from "../_chunks/use-cookie-dDbpCTx-.js";
 import { TimberErrorBoundary } from "./error-boundary.js";
-import React, { createContext, createElement, useActionState as useActionState$1, useContext, useEffect, useMemo, useRef, useSyncExternalStore, useTransition } from "react";
+import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useEffect, useMemo, useRef, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/link-navigate-interceptor.tsx
 /** Symbol used to store the onNavigate callback on anchor elements. */
@@ -349,19 +349,24 @@ var SegmentCache = class {
 	* Only includes sync segments — async segments are excluded because the
 	* server must always re-render them (they may depend on request context).
 	*
+	* When mergeableFilter is provided, only segments whose paths are in the
+	* set are included. This ensures the server only skips segments that the
+	* client can actually merge (i.e., segments whose cached element tree
+	* contains an inner SegmentProvider the merger can splice into).
+	*
 	* This is a performance optimization only, NOT a security boundary.
 	* The server always runs all access.ts files regardless of the state tree.
 	*/
-	serializeStateTree() {
+	serializeStateTree(mergeableFilter) {
 		const segments = [];
-		if (this.root) collectSyncSegments(this.root, segments);
+		if (this.root) collectSyncSegments(this.root, segments, mergeableFilter);
 		return { segments };
 	}
 };
 /** Recursively collect sync segment paths from the tree */
-function collectSyncSegments(node, out) {
-	if (!node.isAsync) out.push(node.segment);
-	for (const child of node.children.values()) collectSyncSegments(child, out);
+function collectSyncSegments(node, out, mergeableFilter) {
+	if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) out.push(node.segment);
+	for (const child of node.children.values()) collectSyncSegments(child, out, mergeableFilter);
 }
 /**
 * Build a SegmentNode tree from flat segment metadata.
@@ -480,27 +485,218 @@ function useParams(_route) {
 	return getSsrData()?.params ?? currentParams;
 }
 //#endregion
-//#region src/client/router.ts
+//#region src/client/segment-merger.ts
 /**
-* Thrown when an RSC payload response contains X-Timber-Redirect header.
-* Caught in navigate() to trigger a soft router navigation to the redirect target.
+* Segment Merger — client-side tree merging for partial RSC payloads.
+*
+* When the server skips rendering sync layouts (because the client already
+* has them cached), the RSC payload is missing outer segment wrappers.
+* This module reconstructs the full element tree by splicing the partial
+* payload into cached segment subtrees.
+*
+* The approach:
+* 1. After each full RSC payload render, walk the decoded element tree
+*    and cache each segment's subtree (identified by SegmentProvider boundaries)
+* 2. When a partial payload arrives, wrap it with cached segment elements
+*    using React.cloneElement to preserve component identity
+*
+* React.cloneElement preserves the element's `type` — React sees the same
+* component at the same tree position and reconciles (preserving state)
+* rather than remounting. This is how layout state survives navigations.
+*
+* Design docs: 19-client-navigation.md §"Navigation Reconciliation"
+* Security: access.ts runs on the server regardless of skipping — this
+*           is a performance optimization only. See 13-security.md.
 */
-var RedirectError = class extends Error {
-	redirectUrl;
-	constructor(url) {
-		super(`Server redirect to ${url}`);
-		this.redirectUrl = url;
+/**
+* Cache of React element subtrees per segment path.
+* Updated after each navigation with the full decoded RSC element tree.
+*/
+var SegmentElementCache = class {
+	entries = /* @__PURE__ */ new Map();
+	get(segmentPath) {
+		return this.entries.get(segmentPath);
+	}
+	set(segmentPath, entry) {
+		this.entries.set(segmentPath, entry);
+	}
+	has(segmentPath) {
+		return this.entries.has(segmentPath);
+	}
+	clear() {
+		this.entries.clear();
+	}
+	get size() {
+		return this.entries.size;
+	}
+	/**
+	* Get the set of segment paths that are safe for the server to skip.
+	* Only segments with an inner SegmentProvider (hasMergeableChild) are
+	* included — the merger can only replace inner SegmentProviders, not
+	* pages embedded in layout output. Used to filter the state tree.
+	*
+	* Returns an empty set if the element cache is empty (no elements
+	* cached yet). This is the safe default — an empty set means no
+	* segments pass the filter, so the state tree is empty and the server
+	* does a full render. The element cache is populated lazily after the
+	* first SPA navigation (RSC-decoded elements from hydration are
+	* thenables that can't be walked until React resolves them).
+	*/
+	getMergeablePaths() {
+		const paths = /* @__PURE__ */ new Set();
+		for (const [, entry] of this.entries) if (entry.hasMergeableChild) paths.add(entry.segmentPath);
+		return paths;
 	}
 };
 /**
-* Check if an error is an abort error (connection closed / fetch aborted).
-* Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
+* Check if a React element is a SegmentProvider by looking for the
+* `segments` prop (an array of path segments). This is the only
+* component that receives this prop shape.
 */
-function isAbortError(error) {
-	if (error instanceof DOMException && error.name === "AbortError") return true;
-	if (error instanceof Error && error.name === "AbortError") return true;
-	return false;
+function isSegmentProvider(element) {
+	if (!isValidElement(element)) return false;
+	const props = element.props;
+	return Array.isArray(props.segments);
+}
+/**
+* Extract the segment path from a SegmentProvider element.
+*
+* Uses the `segmentId` prop if available (set by the server for route groups
+* to distinguish siblings that share the same urlPath). Falls back to
+* reconstructing from the `segments` array prop.
+*/
+function getSegmentPath(element) {
+	const props = element.props;
+	if (props.segmentId) return props.segmentId;
+	const filtered = props.segments.filter(Boolean);
+	return filtered.length === 0 ? "/" : "/" + filtered.join("/");
+}
+/**
+* Walk a React element tree and extract all SegmentProvider boundaries.
+* Returns an ordered list of segment entries from outermost to innermost.
+*
+* This only finds SegmentProviders along the main children path — it does
+* not descend into parallel routes/slots (those are separate subtrees).
+*/
+function extractSegments(element) {
+	const segments = [];
+	walkForSegments(element, segments);
+	for (let i = 0; i < segments.length; i++) segments[i].hasMergeableChild = i < segments.length - 1;
+	return segments;
+}
+function walkForSegments(node, out) {
+	if (!isValidElement(node)) return;
+	const el = node;
+	const props = el.props;
+	if (isSegmentProvider(node)) {
+		out.push({
+			segmentPath: getSegmentPath(el),
+			element: el,
+			hasMergeableChild: false
+		});
+		walkChildren(props.children, out);
+		return;
+	}
+	walkChildren(props.children, out);
+}
+function walkChildren(children, out) {
+	if (children == null) return;
+	if (Array.isArray(children)) for (const child of children) walkForSegments(child, out);
+	else walkForSegments(children, out);
+}
+/**
+* Cache all segment subtrees from a fully-rendered RSC element tree.
+* Call this after every full RSC payload render (navigate, refresh, hydration).
+*/
+function cacheSegmentElements(element, cache) {
+	const segments = extractSegments(element);
+	for (const entry of segments) cache.set(entry.segmentPath, entry);
+}
+function findSegmentProviderPath(node, targetPath) {
+	const children = node.props.children;
+	if (children == null) return null;
+	if (Array.isArray(children)) for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		if (!isValidElement(child)) continue;
+		if (isSegmentProvider(child)) {
+			if (!targetPath || getSegmentPath(child) === targetPath) return [{
+				element: node,
+				childIndex: i
+			}];
+		}
+		const deeper = findSegmentProviderPath(child, targetPath);
+		if (deeper) return [{
+			element: node,
+			childIndex: i
+		}, ...deeper];
+	}
+	else if (isValidElement(children)) {
+		if (isSegmentProvider(children)) {
+			if (!targetPath || getSegmentPath(children) === targetPath) return [{
+				element: node,
+				childIndex: -1
+			}];
+		}
+		const deeper = findSegmentProviderPath(children, targetPath);
+		if (deeper) return [{
+			element: node,
+			childIndex: -1
+		}, ...deeper];
+	}
+	return null;
+}
+/**
+* Replace a nested SegmentProvider within a cached element tree with
+* new content. Uses cloneElement along the path to produce a new tree
+* with preserved component identity at every level except the replaced node.
+*
+* @param cachedElement The cached SegmentProvider element for this segment
+* @param newInnerContent The new React element to splice in at the inner segment position
+* @param innerSegmentPath The path of the inner segment to replace (optional — replaces first found)
+* @returns New element tree with the inner segment replaced
+*/
+function replaceInnerSegment(cachedElement, newInnerContent, innerSegmentPath) {
+	const path = findSegmentProviderPath(cachedElement, innerSegmentPath);
+	if (!path || path.length === 0) return cachedElement;
+	let replacement = newInnerContent;
+	for (let i = path.length - 1; i >= 0; i--) {
+		const { element, childIndex } = path[i];
+		if (childIndex === -1) replacement = cloneElement(element, {}, replacement);
+		else {
+			const newChildren = [...element.props.children];
+			newChildren[childIndex] = replacement;
+			replacement = cloneElement(element, {}, ...newChildren);
+		}
+	}
+	return replacement;
+}
+/**
+* Merge a partial RSC payload with cached segment elements.
+*
+* When the server skips segments, the partial payload starts from the
+* first non-skipped segment. This function wraps it with cached elements
+* for the skipped segments, producing a full tree that React can
+* reconcile with the mounted tree (preserving layout state).
+*
+* @param partialPayload The RSC payload element (may be partial)
+* @param skippedSegments Ordered list of segment paths that were skipped (outermost first)
+* @param cache The segment element cache
+* @returns The merged full element tree, or the partial payload if merging isn't possible
+*/
+function mergeSegmentTree(partialPayload, skippedSegments, cache) {
+	if (!isValidElement(partialPayload)) return partialPayload;
+	if (skippedSegments.length === 0) return partialPayload;
+	let result = partialPayload;
+	for (let i = skippedSegments.length - 1; i >= 0; i--) {
+		const segmentPath = skippedSegments[i];
+		const cached = cache.get(segmentPath);
+		if (!cached) return partialPayload;
+		result = replaceInnerSegment(cached.element, result);
+	}
+	return result;
 }
+//#endregion
+//#region src/client/rsc-fetch.ts
 var RSC_CONTENT_TYPE = "text/x-component";
 /**
 * Generate a short random cache-busting ID (5 chars, a-z0-9).
@@ -557,6 +753,24 @@ function extractSegmentInfo(response) {
 	}
 }
 /**
+* Extract skipped segment paths from the X-Timber-Skipped-Segments header.
+* Returns null if the header is missing or malformed.
+*
+* When the server skips sync layouts the client already has cached,
+* it sends this header listing the skipped segment paths (outermost first).
+* The client uses this to merge the partial payload with cached segments.
+*/
+function extractSkippedSegments(response) {
+	const header = response.headers.get("X-Timber-Skipped-Segments");
+	if (!header) return null;
+	try {
+		const parsed = JSON.parse(header);
+		return Array.isArray(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
 * Extract route params from the X-Timber-Params response header.
 * Returns null if the header is missing or malformed.
 *
@@ -572,6 +786,17 @@ function extractParams(response) {
 	}
 }
 /**
+* Thrown when an RSC payload response contains X-Timber-Redirect header.
+* Caught in navigate() to trigger a soft router navigation to the redirect target.
+*/
+var RedirectError = class extends Error {
+	redirectUrl;
+	constructor(url) {
+		super(`Server redirect to ${url}`);
+		this.redirectUrl = url;
+	}
+};
+/**
 * Fetch an RSC payload from the server. If a decodeRsc function is provided,
 * the response is decoded into a React element tree via createFromFetch.
 * Otherwise, the raw response text is returned (test mode).
@@ -590,12 +815,14 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl) {
 		let headElements = null;
 		let segmentInfo = null;
 		let params = null;
+		let skippedSegments = null;
 		const wrappedPromise = fetchPromise.then((response) => {
 			const redirectLocation = response.headers.get("X-Timber-Redirect") || (response.status >= 300 && response.status < 400 ? response.headers.get("Location") : null);
 			if (redirectLocation) throw new RedirectError(redirectLocation);
 			headElements = extractHeadElements(response);
 			segmentInfo = extractSegmentInfo(response);
 			params = extractParams(response);
+			skippedSegments = extractSkippedSegments(response);
 			return response;
 		});
 		await wrappedPromise;
@@ -603,7 +830,8 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl) {
 			payload: await deps.decodeRsc(wrappedPromise),
 			headElements,
 			segmentInfo,
-			params
+			params,
+			skippedSegments
 		};
 	}
 	const response = await deps.fetch(rscUrl, {
@@ -618,9 +846,21 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl) {
 		payload: await response.text(),
 		headElements: extractHeadElements(response),
 		segmentInfo: extractSegmentInfo(response),
-		params: extractParams(response)
+		params: extractParams(response),
+		skippedSegments: extractSkippedSegments(response)
 	};
 }
+//#endregion
+//#region src/client/router.ts
+/**
+* Check if an error is an abort error (connection closed / fetch aborted).
+* Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
+*/
+function isAbortError(error) {
+	if (error instanceof DOMException && error.name === "AbortError") return true;
+	if (error instanceof Error && error.name === "AbortError") return true;
+	return false;
+}
 /**
 * Create a router instance. In production, called once at app hydration
 * with real browser APIs. In tests, called with mock dependencies.
@@ -629,6 +869,7 @@ function createRouter(deps) {
 	const segmentCache = new SegmentCache();
 	const prefetchCache = new PrefetchCache();
 	const historyStack = new HistoryStack();
+	const segmentElementCache = new SegmentElementCache();
 	let pending = false;
 	let pendingUrl = null;
 	const pendingListeners = /* @__PURE__ */ new Set();
@@ -650,6 +891,17 @@ function createRouter(deps) {
 		if (deps.renderRoot) deps.renderRoot(payload);
 	}
 	/**
+	* Merge a partial RSC payload with cached segment elements if segments
+	* were skipped, then cache segments from the (merged) payload.
+	* Returns the merged payload ready for rendering.
+	*/
+	function mergeAndCachePayload(payload, skippedSegments) {
+		let merged = payload;
+		if (skippedSegments && skippedSegments.length > 0) merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+		cacheSegmentElements(merged, segmentElementCache);
+		return merged;
+	}
+	/**
 	* Update navigation state (params + pathname) for the next render.
 	*
 	* Sets both the module-level fallback (for tests and SSR) and the
@@ -671,18 +923,30 @@ function createRouter(deps) {
 	* In production, the entire callback runs inside a React transition with
 	* useOptimistic for the pending URL. In tests, the payload is rendered directly.
 	*/
-	async function renderViaTransition(pendingUrl, perform) {
+	async function renderViaTransition(url, perform) {
 		if (deps.navigateTransition) {
 			let headElements = null;
-			await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
+			await deps.navigateTransition(url, async (wrapPayload) => {
 				const result = await perform();
 				headElements = result.headElements;
-				return wrapPayload(result.payload);
+				const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+				historyStack.push(url, {
+					payload: merged,
+					headElements: result.headElements,
+					params: result.params
+				});
+				return wrapPayload(merged);
 			});
 			return headElements;
 		}
 		const result = await perform();
-		renderPayload(result.payload);
+		const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+		historyStack.push(url, {
+			payload: merged,
+			headElements: result.headElements,
+			params: result.params
+		});
+		renderPayload(merged);
 		return result.headElements;
 	}
 	/** Apply head elements (title, meta tags) to the DOM if available. */
@@ -704,10 +968,11 @@ function createRouter(deps) {
 			payload: prefetched.payload,
 			headElements: prefetched.headElements,
 			segmentInfo: prefetched.segmentInfo ?? null,
-			params: prefetched.params ?? null
+			params: prefetched.params ?? null,
+			skippedSegments: prefetched.skippedSegments ?? null
 		} : void 0;
 		if (result === void 0) {
-			const stateTree = segmentCache.serializeStateTree();
+			const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
 			const rawCurrentUrl = deps.getCurrentUrl();
 			result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname);
 		}
@@ -719,11 +984,6 @@ function createRouter(deps) {
 			timber: true,
 			scrollY: 0
 		}, "", url);
-		historyStack.push(url, {
-			payload: result.payload,
-			headElements: result.headElements,
-			params: result.params
-		});
 		updateSegmentCache(result.segmentInfo);
 		updateNavigationState(result.params, url);
 		return result;
@@ -763,11 +1023,6 @@ function createRouter(deps) {
 		try {
 			applyHead(await renderViaTransition(currentUrl, async () => {
 				const result = await fetchRscPayload(currentUrl, deps);
-				historyStack.push(currentUrl, {
-					payload: result.payload,
-					headElements: result.headElements,
-					params: result.params
-				});
 				updateSegmentCache(result.segmentInfo);
 				updateNavigationState(result.params, currentUrl);
 				return result;
@@ -790,14 +1045,9 @@ function createRouter(deps) {
 			setPending(true, url);
 			try {
 				applyHead(await renderViaTransition(url, async () => {
-					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree());
+					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()));
 					updateSegmentCache(result.segmentInfo);
 					updateNavigationState(result.params, url);
-					historyStack.push(url, {
-						payload: result.payload,
-						headElements: result.headElements,
-						params: result.params
-					});
 					return result;
 				}));
 				afterPaint(() => {
@@ -816,7 +1066,7 @@ function createRouter(deps) {
 	function prefetch(url) {
 		if (prefetchCache.get(url) !== void 0) return;
 		if (historyStack.has(url)) return;
-		fetchRscPayload(url, deps, segmentCache.serializeStateTree()).then((result) => {
+		fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths())).then((result) => {
 			prefetchCache.set(url, result);
 		}, () => {});
 	}
@@ -833,14 +1083,16 @@ function createRouter(deps) {
 		prefetch,
 		applyRevalidation(element, headElements) {
 			const currentUrl = deps.getCurrentUrl();
+			const merged = mergeAndCachePayload(element, null);
 			historyStack.push(currentUrl, {
-				payload: element,
+				payload: merged,
 				headElements
 			});
-			renderPayload(element);
+			renderPayload(merged);
 			applyHead(headElements);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
+		cacheElementTree: (element) => cacheSegmentElements(element, segmentElementCache),
 		segmentCache,
 		prefetchCache,
 		historyStack
@@ -1105,7 +1357,7 @@ function useSegmentContext() {
 * Wraps each layout to provide segment position context.
 * Injected by rsc-entry.ts during element tree construction.
 */
-function SegmentProvider({ segments, parallelRouteKeys, children }) {
+function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }) {
 	const value = useMemo(() => ({
 		segments,
 		parallelRouteKeys