@timber-js/app 0.1.52 → 0.1.53

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. */
@@ -480,27 +480,194 @@ 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;
 	}
 };
 /**
-* 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.
+* The `segments` prop is an array like ["", "dashboard", "settings"].
+* The path is reconstructed as "/" + segments.filter(Boolean).join("/").
+*/
+function getSegmentPath(element) {
+	const filtered = element.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);
+	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
+		});
+		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 cloneElement(cachedElement, {}, newInnerContent);
+	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 +724,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 +757,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 +786,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 +801,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 +817,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 +840,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 +862,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
@@ -677,12 +900,12 @@ function createRouter(deps) {
 			await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
 				const result = await perform();
 				headElements = result.headElements;
-				return wrapPayload(result.payload);
+				return wrapPayload(mergeAndCachePayload(result.payload, result.skippedSegments));
 			});
 			return headElements;
 		}
 		const result = await perform();
-		renderPayload(result.payload);
+		renderPayload(mergeAndCachePayload(result.payload, result.skippedSegments));
 		return result.headElements;
 	}
 	/** Apply head elements (title, meta tags) to the DOM if available. */
@@ -704,7 +927,8 @@ 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();
@@ -833,14 +1057,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