@timber-js/app 0.1.52 → 0.1.53

package/dist/client/rsc-fetch.d.ts

@@ -0,0 +1,80 @@
+/**
+ * RSC Fetch — handles fetching and parsing RSC Flight payloads.
+ *
+ * Extracted from router.ts to keep both files under the 500-line limit.
+ * This module handles:
+ * - Cache-busting URL generation for RSC requests
+ * - Building RSC request headers (Accept, X-Timber-State-Tree)
+ * - Extracting metadata from RSC response headers
+ * - Fetching and decoding RSC payloads
+ *
+ * See design/19-client-navigation.md §"RSC Payload Handling"
+ */
+import type { SegmentInfo } from './segment-cache';
+import type { HeadElement } from './head';
+import type { RouterDeps } from './router';
+/** Result of fetching an RSC payload — includes head elements and segment metadata. */
+export interface FetchResult {
+    payload: unknown;
+    headElements: HeadElement[] | null;
+    /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
+    segmentInfo: SegmentInfo[] | null;
+    /** Route params from X-Timber-Params header for populating useParams(). */
+    params: Record<string, string | string[]> | null;
+    /** Segment paths that were skipped by the server (for client-side merging). */
+    skippedSegments: string[] | null;
+}
+export declare const RSC_CONTENT_TYPE = "text/x-component";
+export declare function buildRscHeaders(stateTree: {
+    segments: string[];
+} | undefined, currentUrl?: string): Record<string, string>;
+/**
+ * Extract head elements from the X-Timber-Head response header.
+ * Returns null if the header is missing or malformed.
+ */
+export declare function extractHeadElements(response: Response): HeadElement[] | null;
+/**
+ * Extract segment metadata from the X-Timber-Segments response header.
+ * Returns null if the header is missing or malformed.
+ *
+ * Format: JSON array of {path, isAsync} objects describing the rendered
+ * segment chain from root to leaf. Used to populate the client-side
+ * segment cache for state tree diffing on subsequent navigations.
+ */
+export declare function extractSegmentInfo(response: Response): SegmentInfo[] | null;
+/**
+ * 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.
+ */
+export declare function extractSkippedSegments(response: Response): string[] | null;
+/**
+ * Extract route params from the X-Timber-Params response header.
+ * Returns null if the header is missing or malformed.
+ *
+ * Used to populate useParams() after client-side navigation.
+ */
+export declare function extractParams(response: Response): Record<string, string | string[]> | null;
+/**
+ * Thrown when an RSC payload response contains X-Timber-Redirect header.
+ * Caught in navigate() to trigger a soft router navigation to the redirect target.
+ */
+export declare class RedirectError extends Error {
+    readonly redirectUrl: string;
+    constructor(url: string);
+}
+/**
+ * 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).
+ *
+ * Also extracts head elements from the X-Timber-Head response header
+ * so the client can update document.title and <meta> tags after navigation.
+ */
+export declare function fetchRscPayload(url: string, deps: RouterDeps, stateTree?: {
+    segments: string[];
+}, currentUrl?: string): Promise<FetchResult>;
+//# sourceMappingURL=rsc-fetch.d.ts.map

package/dist/client/rsc-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-fetch.d.ts","sourceRoot":"","sources":["../../src/client/rsc-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3C,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,uFAAuF;IACvF,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACjD,+EAA+E;IAC/E,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAClC;AAID,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AA2BnD,wBAAgB,eAAe,CAC7B,SAAS,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,EAC7C,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI,CAQ5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI,CAQ3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,GAAG,IAAI,CAS1E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAQ1F;AAID;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,GAAG,EAAE,MAAM;CAIxB;AAID;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,EAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAuDtB"}

package/dist/client/segment-cache.d.ts

@@ -7,6 +7,8 @@ export interface PrefetchResult {
     segmentInfo?: SegmentInfo[] | null;
     /** Route params from X-Timber-Params header for populating useParams(). */
     params?: Record<string, string | string[]> | null;
+    /** Segment paths skipped by the server (for client-side merging). */
+    skippedSegments?: string[] | null;
 }
 /**
  * A node in the client-side segment tree. Each node represents a mounted

package/dist/client/segment-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"segment-cache.d.ts","sourceRoot":"","sources":["../../src/client/segment-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAI1C,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,uFAAuF;IACvF,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAA0B;IAEtC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAO7C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI;IAM7C,KAAK,IAAI,IAAI;IAIb;;;;;;;OAOG;IACH,kBAAkB,IAAI,SAAS;CAOhC;AAcD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CA+BjF;AASD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAU;IACxC,OAAO,CAAC,OAAO,CAAoC;IAEnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI;IAO9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAU5C,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;CAOjD"}
+{"version":3,"file":"segment-cache.d.ts","sourceRoot":"","sources":["../../src/client/segment-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAI1C,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,uFAAuF;IACvF,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAClD,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAA0B;IAEtC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAO7C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI;IAM7C,KAAK,IAAI,IAAI;IAIb;;;;;;;OAOG;IACH,kBAAkB,IAAI,SAAS;CAOhC;AAcD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CA+BjF;AASD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAU;IACxC,OAAO,CAAC,OAAO,CAAoC;IAEnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI;IAO9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAU5C,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;CAOjD"}

package/dist/client/segment-merger.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import { type ReactElement, type ReactNode } from 'react';
+/**
+ * A cached segment entry. Stores the full subtree rooted at a SegmentProvider
+ * and the path through the tree to the next SegmentProvider (or leaf).
+ */
+export interface CachedSegmentEntry {
+    /** The segment's URL path (e.g., "/", "/dashboard") */
+    segmentPath: string;
+    /** The SegmentProvider element for this segment */
+    element: ReactElement;
+}
+/**
+ * Cache of React element subtrees per segment path.
+ * Updated after each navigation with the full decoded RSC element tree.
+ */
+export declare class SegmentElementCache {
+    private entries;
+    get(segmentPath: string): CachedSegmentEntry | undefined;
+    set(segmentPath: string, entry: CachedSegmentEntry): void;
+    has(segmentPath: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * 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.
+ */
+export declare function isSegmentProvider(element: unknown): element is ReactElement;
+/**
+ * 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("/").
+ */
+export declare function getSegmentPath(element: ReactElement): string;
+/**
+ * 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).
+ */
+export declare function extractSegments(element: unknown): CachedSegmentEntry[];
+/**
+ * Cache all segment subtrees from a fully-rendered RSC element tree.
+ * Call this after every full RSC payload render (navigate, refresh, hydration).
+ */
+export declare function cacheSegmentElements(element: unknown, cache: SegmentElementCache): void;
+/**
+ * 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
+ */
+export declare function replaceInnerSegment(cachedElement: ReactElement, newInnerContent: ReactNode, innerSegmentPath?: string): ReactElement;
+/**
+ * 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
+ */
+export declare function mergeSegmentTree(partialPayload: unknown, skippedSegments: string[], cache: SegmentElementCache): unknown;
+//# sourceMappingURL=segment-merger.d.ts.map

package/dist/client/segment-merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-merger.d.ts","sourceRoot":"","sources":["../../src/client/segment-merger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAgC,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIxF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,OAAO,EAAE,YAAY,CAAC;CACvB;AAID;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAyC;IAExD,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIxD,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAIzD,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIjC,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,YAAY,CAI3E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAI5D;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,kBAAkB,EAAE,CAItE;AAsCD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,mBAAmB,GACzB,IAAI,CAKN;AAqDD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,YAAY,EAC3B,eAAe,EAAE,SAAS,EAC1B,gBAAgB,CAAC,EAAE,MAAM,GACxB,YAAY,CA6Bd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,MAAM,EAAE,EACzB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CA0BT"}

package/dist/server/route-element-builder.d.ts

@@ -41,6 +41,13 @@ export interface RouteElementResult {
     segments: ManifestSegmentNode[];
     /** Max deferSuspenseFor hold window across all segments. */
     deferSuspenseFor: number;
+    /**
+     * Segment paths that were skipped because the client already has them cached.
+     * Ordered outermost to innermost. Empty when no segments were skipped.
+     * The client uses this to merge the partial payload with cached segments.
+     * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+     */
+    skippedSegments: string[];
 }
 /**
  * Wraps a DenySignal or RedirectSignal with the layout components loaded

package/dist/server/route-element-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAKzD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAgU7B"}
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAKzD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAuU7B"}

package/dist/server/rsc-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAwXD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;8BA5P3C,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA8PhD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAyXD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;8BA7P3C,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA+PhD,wBAAiE"}

package/dist/server/rsc-entry/rsc-payload.d.ts

@@ -21,5 +21,5 @@ import type { RenderSignals } from './rsc-stream.js';
  * initial component tree, allowing onError to capture DenySignal/
  * RedirectSignal before we commit the response. See TIM-344.
  */
-export declare function buildRscPayloadResponse(req: Request, rscStream: ReadableStream<Uint8Array>, signals: RenderSignals, segments: ManifestSegmentNode[], layoutComponents: LayoutComponentEntry[], headElements: HeadElement[], match: RouteMatch, responseHeaders: Headers): Promise<Response>;
+export declare function buildRscPayloadResponse(req: Request, rscStream: ReadableStream<Uint8Array>, signals: RenderSignals, segments: ManifestSegmentNode[], layoutComponents: LayoutComponentEntry[], headElements: HeadElement[], match: RouteMatch, responseHeaders: Headers, skippedSegments?: string[]): Promise<Response>;
 //# sourceMappingURL=rsc-payload.d.ts.map

package/dist/server/rsc-entry/rsc-payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsc-payload.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAQrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,YAAY,EAAE,WAAW,EAAE,EAC3B,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,GACvB,OAAO,CAAC,QAAQ,CAAC,CAiFnB"}
+{"version":3,"file":"rsc-payload.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAQrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,YAAY,EAAE,WAAW,EAAE,EAC3B,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,QAAQ,CAAC,CAuFnB"}

package/dist/server/state-tree-diff.d.ts

@@ -39,5 +39,5 @@ export declare function parseClientStateTree(req: Request): Set<string> | null;
  * @param isLeaf - Whether this is the leaf segment (page segment)
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
-export declare function shouldSkipSegment(_urlPath: string, _layoutComponent: ((...args: unknown[]) => unknown) | undefined, _isLeaf: boolean, _clientSegments: Set<string> | null): boolean;
+export declare function shouldSkipSegment(urlPath: string, layoutComponent: ((...args: unknown[]) => unknown) | undefined, isLeaf: boolean, clientSegments: Set<string> | null): boolean;
 //# sourceMappingURL=state-tree-diff.d.ts.map

package/dist/server/state-tree-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAarE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC/D,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAClC,OAAO,CAgBT"}
+{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAarE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC9D,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACjC,OAAO,CAeT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry.ts

@@ -545,6 +545,13 @@ function bootstrap(runtimeConfig: typeof config): void {
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
 
+  // Cache segment elements from the initial RSC payload for client-side
+  // tree merging. This ensures the first client navigation can use partial
+  // payloads — the merger needs cached elements for skipped segments.
+  if (initialElement) {
+    router.cacheElementTree(initialElement);
+  }
+
   // Note: __timber_params is read before hydrateRoot (see above) so that
   // NavigationProvider has correct values during hydration. If the hydration
   // path was skipped (no RSC payload), populate the fallback here.

package/src/client/router.ts

@@ -7,6 +7,13 @@ import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
 import { setNavigationState } from './navigation-context.js';
+import {
+  SegmentElementCache,
+  cacheSegmentElements,
+  mergeSegmentTree,
+} from './segment-merger.js';
+import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
+import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -71,16 +78,6 @@ export interface RouterDeps {
   ) => Promise<void>;
 }
 
-/** Result of fetching an RSC payload — includes head elements and segment metadata. */
-interface FetchResult {
-  payload: unknown;
-  headElements: HeadElement[] | null;
-  /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
-  segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
-  params: Record<string, string | string[]> | null;
-}
-
 export interface RouterInstance {
   /** Navigate to a new URL (forward navigation) */
   navigate(url: string, options?: NavigationOptions): Promise<void>;
@@ -107,6 +104,12 @@ export interface RouterInstance {
    * Called on initial hydration with segment info embedded in the HTML.
    */
   initSegmentCache(segments: SegmentInfo[]): void;
+  /**
+   * Cache segment elements from a decoded RSC element tree.
+   * Called on initial hydration to populate the element cache so the
+   * first client navigation can use partial payloads.
+   */
+  cacheElementTree(element: unknown): void;
   /** The segment cache (exposed for tests and <Link> prefetch) */
   segmentCache: SegmentCache;
   /** The prefetch cache (exposed for tests and <Link> prefetch) */
@@ -115,18 +118,6 @@ export interface RouterInstance {
   historyStack: HistoryStack;
 }
 
-/**
- * Thrown when an RSC payload response contains X-Timber-Redirect header.
- * Caught in navigate() to trigger a soft router navigation to the redirect target.
- */
-class RedirectError extends Error {
-  readonly redirectUrl: string;
-  constructor(url: string) {
-    super(`Server redirect to ${url}`);
-    this.redirectUrl = url;
-  }
-}
-
 /**
  * Check if an error is an abort error (connection closed / fetch aborted).
  * Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
@@ -137,168 +128,6 @@ function isAbortError(error: unknown): boolean {
   return false;
 }
 
-// ─── RSC Fetch ───────────────────────────────────────────────────
-
-const RSC_CONTENT_TYPE = 'text/x-component';
-
-/**
- * Generate a short random cache-busting ID (5 chars, a-z0-9).
- * Matches the format Next.js uses for _rsc params.
- */
-function generateCacheBustId(): string {
-  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
-  let id = '';
-  for (let i = 0; i < 5; i++) {
-    id += chars[(Math.random() * 36) | 0];
-  }
-  return id;
-}
-
-/**
- * Append a `_rsc=<id>` query parameter to the URL.
- * Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
- * for RSC navigation requests and signals that this is an RSC fetch.
- */
-function appendRscParam(url: string): string {
-  const separator = url.includes('?') ? '&' : '?';
-  return `${url}${separator}_rsc=${generateCacheBustId()}`;
-}
-
-function buildRscHeaders(
-  stateTree: { segments: string[] } | undefined,
-  currentUrl?: string
-): Record<string, string> {
-  const headers: Record<string, string> = {
-    Accept: RSC_CONTENT_TYPE,
-  };
-  if (stateTree) {
-    headers['X-Timber-State-Tree'] = JSON.stringify(stateTree);
-  }
-  // Send current URL for intercepting route resolution.
-  // The server uses this to determine if an intercepting route should
-  // render instead of the actual target route (modal pattern).
-  // See design/07-routing.md §"Intercepting Routes"
-  if (currentUrl) {
-    headers['X-Timber-URL'] = currentUrl;
-  }
-  return headers;
-}
-
-/**
- * Extract head elements from the X-Timber-Head response header.
- * Returns null if the header is missing or malformed.
- */
-function extractHeadElements(response: Response): HeadElement[] | null {
-  const header = response.headers.get('X-Timber-Head');
-  if (!header) return null;
-  try {
-    return JSON.parse(decodeURIComponent(header));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Extract segment metadata from the X-Timber-Segments response header.
- * Returns null if the header is missing or malformed.
- *
- * Format: JSON array of {path, isAsync} objects describing the rendered
- * segment chain from root to leaf. Used to populate the client-side
- * segment cache for state tree diffing on subsequent navigations.
- */
-function extractSegmentInfo(response: Response): SegmentInfo[] | null {
-  const header = response.headers.get('X-Timber-Segments');
-  if (!header) return null;
-  try {
-    return JSON.parse(header);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Extract route params from the X-Timber-Params response header.
- * Returns null if the header is missing or malformed.
- *
- * Used to populate useParams() after client-side navigation.
- */
-function extractParams(response: Response): Record<string, string | string[]> | null {
-  const header = response.headers.get('X-Timber-Params');
-  if (!header) return null;
-  try {
-    return JSON.parse(header);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 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).
- *
- * Also extracts head elements from the X-Timber-Head response header
- * so the client can update document.title and <meta> tags after navigation.
- */
-async function fetchRscPayload(
-  url: string,
-  deps: RouterDeps,
-  stateTree?: { segments: string[] },
-  currentUrl?: string
-): Promise<FetchResult> {
-  const rscUrl = appendRscParam(url);
-  const headers = buildRscHeaders(stateTree, currentUrl);
-  if (deps.decodeRsc) {
-    // Production path: use createFromFetch for streaming RSC decoding.
-    // createFromFetch takes a Promise<Response> and progressively parses
-    // the RSC Flight stream as chunks arrive.
-    //
-    // Intercept the response to read X-Timber-Head before createFromFetch
-    // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual' });
-    let headElements: HeadElement[] | null = null;
-    let segmentInfo: SegmentInfo[] | null = null;
-    let params: Record<string, string | string[]> | null = null;
-    const wrappedPromise = fetchPromise.then((response) => {
-      // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
-      // for RSC payload requests instead of a raw 302, because fetch with
-      // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
-      // which crashes createFromFetch when it tries to read the body stream.
-      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);
-      return response;
-    });
-    // Await so headElements/segmentInfo/params are populated before we return.
-    // Also await the decoded payload — createFromFetch returns a thenable
-    // that resolves to the React element tree.
-    await wrappedPromise;
-    const payload = await deps.decodeRsc(wrappedPromise);
-    return { payload, headElements, segmentInfo, params };
-  }
-  // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
-  // Check for redirect in test path too
-  if (response.status >= 300 && response.status < 400) {
-    const location = response.headers.get('Location');
-    if (location) {
-      throw new RedirectError(location);
-    }
-  }
-  return {
-    payload: await response.text(),
-    headElements: extractHeadElements(response),
-    segmentInfo: extractSegmentInfo(response),
-    params: extractParams(response),
-  };
-}
-
 // ─── Router Factory ──────────────────────────────────────────────
 
 /**
@@ -309,6 +138,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentCache = new SegmentCache();
   const prefetchCache = new PrefetchCache();
   const historyStack = new HistoryStack();
+  const segmentElementCache = new SegmentElementCache();
 
   let pending = false;
   let pendingUrl: string | null = null;
@@ -343,6 +173,28 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * 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: unknown,
+    skippedSegments: string[] | null | undefined
+  ): unknown {
+    let merged = payload;
+
+    // If segments were skipped, merge the partial payload with cached segments
+    if (skippedSegments && skippedSegments.length > 0) {
+      merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+    }
+
+    // Cache segment elements from the (merged) payload for future merges
+    cacheSegmentElements(merged, segmentElementCache);
+
+    return merged;
+  }
+
   /**
    * Update navigation state (params + pathname) for the next render.
    *
@@ -378,13 +230,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
         const result = await perform();
         headElements = result.headElements;
-        return wrapPayload(result.payload);
+        // Merge partial payload with cached segments before wrapping
+        const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+        return wrapPayload(merged);
       });
       return headElements;
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
-    renderPayload(result.payload);
+    // Merge partial payload with cached segments before rendering
+    const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+    renderPayload(merged);
     return result.headElements;
   }
 
@@ -421,6 +277,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: prefetched.headElements,
           segmentInfo: prefetched.segmentInfo ?? null,
           params: prefetched.params ?? null,
+          skippedSegments: prefetched.skippedSegments ?? null,
         }
       : undefined;
 
@@ -616,15 +473,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Render the piggybacked element tree from a server action response.
       // Updates the current history entry with the fresh payload and applies
       // head elements — same as refresh() but without a server fetch.
+      // Cache segment elements for future partial merges.
       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: SegmentInfo[]) => updateSegmentCache(segments),
+    cacheElementTree: (element: unknown) => cacheSegmentElements(element, segmentElementCache),
     segmentCache,
     prefetchCache,
     historyStack,