@timber-js/app 0.1.51 → 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/client/stale-reload.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Stale Client Reference Reload
+ *
+ * When a new deployment ships updated bundles, clients running stale
+ * JavaScript may encounter "Could not find the module" errors during
+ * RSC Flight stream decoding. This happens because the RSC payload
+ * references module IDs from the new bundle that don't exist in the
+ * old client bundle.
+ *
+ * This module detects these specific errors and triggers a full page
+ * reload so the browser fetches the new bundle. A sessionStorage flag
+ * guards against infinite reload loops.
+ *
+ * See: LOCAL-332
+ */
+/**
+ * Check if an error is a stale client reference error from React's
+ * Flight client. These errors have the message pattern:
+ *   "Could not find the module \"<id>\""
+ *
+ * This is thrown by react-server-dom-webpack's client when the RSC
+ * payload references a module ID that doesn't exist in the client's
+ * module map — typically because the server has been redeployed with
+ * new bundle hashes while the client is still running old JavaScript.
+ */
+export declare function isStaleClientReference(error: unknown): boolean;
+/**
+ * Trigger a full page reload to pick up new bundles.
+ *
+ * Sets a sessionStorage flag before reloading. If the flag is already
+ * set (meaning we already reloaded once for this reason), we don't
+ * reload again — this prevents infinite reload loops if the error
+ * persists after reload (e.g., a genuine bug rather than a stale bundle).
+ *
+ * @returns true if a reload was triggered, false if suppressed (loop guard)
+ */
+export declare function triggerStaleReload(): boolean;
+/**
+ * Clear the stale reload flag. Called on successful bootstrap to reset
+ * the loop guard — if the page loaded successfully, the next stale
+ * reference error should trigger a fresh reload attempt.
+ */
+export declare function clearStaleReloadFlag(): void;
+//# sourceMappingURL=stale-reload.d.ts.map

package/dist/client/stale-reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-reload.d.ts","sourceRoot":"","sources":["../../src/client/stale-reload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CA+B5C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C"}

package/dist/index.js

@@ -11560,7 +11560,21 @@ var NO_COMPRESS_STATUSES = new Set([204, 304]);
 */
 function negotiateEncoding(acceptEncoding) {
 	if (!acceptEncoding) return null;
-	if (acceptEncoding.split(",").map((s) => s.split(";")[0].trim().toLowerCase()).includes("gzip")) return "gzip";
+	const parts = acceptEncoding.split(",");
+	for (const part of parts) {
+		const [token, ...params] = part.split(";");
+		if (token.trim().toLowerCase() !== "gzip") continue;
+		let qValue = 1;
+		for (const param of params) {
+			const trimmed = param.trim().toLowerCase();
+			if (trimmed.startsWith("q=")) {
+				qValue = parseFloat(trimmed.slice(2));
+				if (Number.isNaN(qValue)) qValue = 1;
+				break;
+			}
+		}
+		if (qValue > 0) return "gzip";
+	}
 	return null;
 }
 /**