@timber-js/app 0.1.53 → 0.1.55

package/dist/client/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/client/router.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/client/router.ts"],"names":[],"mappings":"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"}

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

@@ -46,10 +46,15 @@ export declare class SegmentCache {
      * 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(): StateTree;
+    serializeStateTree(mergeableFilter?: Set<string>): StateTree;
 }
 /**
  * Segment metadata from the server, sent via X-Timber-Segments header.

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;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"}
+{"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;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS;CAO7D;AAkBD;;;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-context.d.ts

@@ -20,6 +20,13 @@ export interface SegmentContextValue {
 export declare function useSegmentContext(): SegmentContextValue | null;
 interface SegmentProviderProps {
     segments: string[];
+    /**
+     * Unique identifier for this segment, used by the client-side segment
+     * merger for element caching. For route groups this includes the group
+     * name (e.g., "/(marketing)") since groups share their parent's urlPath.
+     * Falls back to the reconstructed path from `segments` if not provided.
+     */
+    segmentId?: string;
     parallelRouteKeys: string[];
     children: React.ReactNode;
 }
@@ -27,6 +34,6 @@ interface SegmentProviderProps {
  * Wraps each layout to provide segment position context.
  * Injected by rsc-entry.ts during element tree construction.
  */
-export declare function SegmentProvider({ segments, parallelRouteKeys, children }: SegmentProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SegmentContextValue | null>>;
+export declare function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }: SegmentProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SegmentContextValue | null>>;
 export {};
 //# sourceMappingURL=segment-context.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"segment-context.d.ts","sourceRoot":"","sources":["../../src/client/segment-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0FAA0F;IAC1F,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAMD,qFAAqF;AACrF,wBAAgB,iBAAiB,IAAI,mBAAmB,GAAG,IAAI,CAE9D;AAID,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,EAAE,oBAAoB,uGAS9F"}
+{"version":3,"file":"segment-context.d.ts","sourceRoot":"","sources":["../../src/client/segment-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0FAA0F;IAC1F,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAMD,qFAAqF;AACrF,wBAAgB,iBAAiB,IAAI,mBAAmB,GAAG,IAAI,CAE9D;AAID,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,EAAE,oBAAoB,uGASrH"}

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

@@ -30,6 +30,13 @@ export interface CachedSegmentEntry {
     segmentPath: string;
     /** The SegmentProvider element for this segment */
     element: ReactElement;
+    /**
+     * Whether this segment's cached element contains a nested SegmentProvider.
+     * Only segments with inner SegmentProviders are safe to skip — the merger
+     * can only replace inner SegmentProviders, not pages embedded in layout output.
+     * Used by the state tree serialization to exclude non-mergeable segments.
+     */
+    hasMergeableChild: boolean;
 }
 /**
  * Cache of React element subtrees per segment path.
@@ -42,6 +49,20 @@ export declare class SegmentElementCache {
     has(segmentPath: string): boolean;
     clear(): void;
     get size(): number;
+    /**
+     * 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(): Set<string>;
 }
 /**
  * Check if a React element is a SegmentProvider by looking for the
@@ -51,8 +72,10 @@ export declare class SegmentElementCache {
 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("/").
+ *
+ * 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.
  */
 export declare function getSegmentPath(element: ReactElement): string;
 /**

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

@@ -1 +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"}
+{"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;IACtB;;;;;OAKG;IACH,iBAAiB,EAAE,OAAO,CAAC;CAC5B;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;IAED;;;;;;;;;;;;OAYG;IACH,iBAAiB,IAAI,GAAG,CAAC,MAAM,CAAC;CASjC;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,YAAY,CAI3E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAM5D;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,kBAAkB,EAAE,CAUtE;AAuCD;;;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,CAoCd;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.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;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"}
+{"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,CA2W7B"}

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,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"}
+{"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,CAeT"}

package/package.json

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

package/src/adapters/nitro.ts

@@ -341,20 +341,24 @@ export function generateNitroEntry(
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}import { defineEventHandler } from 'nitro/h3'
-import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
+${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
 import { compressResponse } from './_compress.mjs'
 
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
 
-export default defineEventHandler(async (event) => {
+// Nitro's index.mjs wraps this import with defineLazyEventHandler, which
+// already handles the event handler protocol. We export a plain async
+// function — no defineEventHandler wrapper needed.
+// Nitro bundles h3 into its internal _libs/ directory but doesn't make
+// it available as a bare specifier in the output's node_modules.
+export default async function timberHandler(event) {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
   return compressResponse(webRequest, webResponse)
-})
+}
 `;
 }
 

package/src/client/browser-entry.ts

@@ -545,12 +545,12 @@ 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: We do NOT cache segment elements from the initial RSC payload here.
+  // The decoded element from createFromReadableStream is a thenable/lazy
+  // element that React resolves during render — the segment walker can't
+  // traverse it. The element cache is populated lazily after the first SPA
+  // navigation (via mergeAndCachePayload in renderViaTransition), when
+  // the decoded payload is a fully resolved React element tree.
 
   // Note: __timber_params is read before hydrateRoot (see above) so that
   // NavigationProvider has correct values during hydration. If the hydration

package/src/client/router.ts

@@ -222,16 +222,23 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * useOptimistic for the pending URL. In tests, the payload is rendered directly.
    */
   async function renderViaTransition(
-    pendingUrl: string,
+    url: string,
     perform: () => Promise<FetchResult>
   ): Promise<HeadElement[] | null> {
     if (deps.navigateTransition) {
       let headElements: HeadElement[] | null = null;
-      await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
+      await deps.navigateTransition(url, async (wrapPayload) => {
         const result = await perform();
         headElements = result.headElements;
         // Merge partial payload with cached segments before wrapping
         const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+        // Store the MERGED payload in history — not the partial pre-merge tree.
+        // This ensures handlePopState replays the complete tree on back/forward.
+        historyStack.push(url, {
+          payload: merged,
+          headElements: result.headElements,
+          params: result.params,
+        });
         return wrapPayload(merged);
       });
       return headElements;
@@ -240,6 +247,12 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const result = await perform();
     // Merge partial payload with cached segments before rendering
     const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+    // Store merged payload in history
+    historyStack.push(url, {
+      payload: merged,
+      headElements: result.headElements,
+      params: result.params,
+    });
     renderPayload(merged);
     return result.headElements;
   }
@@ -284,7 +297,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (result === undefined) {
       // Fetch RSC payload with state tree for partial rendering.
       // Send current URL for intercepting route resolution (modal pattern).
-      const stateTree = segmentCache.serializeStateTree();
+      const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
       const rawCurrentUrl = deps.getCurrentUrl();
       const currentUrl = rawCurrentUrl.startsWith('http')
         ? new URL(rawCurrentUrl).pathname
@@ -299,12 +312,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.pushState({ timber: true, scrollY: 0 }, '', url);
     }
 
-    // Store the payload in the history stack
-    historyStack.push(url, {
-      payload: result.payload,
-      headElements: result.headElements,
-      params: result.params,
-    });
+    // NOTE: History push is deferred — the merged payload (after segment
+    // merging in renderViaTransition) is stored by the caller, not here.
+    // Storing result.payload here would record the partial (pre-merge)
+    // RSC tree, causing handlePopState to replay an incomplete tree.
 
     // Update the segment cache with the new route's segment tree.
     updateSegmentCache(result.segmentInfo);
@@ -375,11 +386,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       const headElements = await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(currentUrl, deps);
-        historyStack.push(currentUrl, {
-          payload: result.payload,
-          headElements: result.headElements,
-          params: result.params,
-        });
+        // History push handled by renderViaTransition (stores merged payload)
         updateSegmentCache(result.segmentInfo);
         updateNavigationState(result.params, currentUrl);
         return result;
@@ -414,15 +421,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       setPending(true, url);
       try {
         const headElements = await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree();
+          const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
           const result = await fetchRscPayload(url, deps, stateTree);
           updateSegmentCache(result.segmentInfo);
           updateNavigationState(result.params, url);
-          historyStack.push(url, {
-            payload: result.payload,
-            headElements: result.headElements,
-            params: result.params,
-          });
+          // History push handled by renderViaTransition (stores merged payload)
           return result;
         });
 
@@ -447,7 +450,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (historyStack.has(url)) return;
 
     // Fire-and-forget fetch
-    const stateTree = segmentCache.serializeStateTree();
+    const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
     void fetchRscPayload(url, deps, stateTree).then(
       (result) => {
         prefetchCache.set(url, result);

package/src/client/segment-cache.ts

@@ -72,25 +72,34 @@ export class SegmentCache {
    * 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(): StateTree {
+  serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
     if (this.root) {
-      collectSyncSegments(this.root, segments);
+      collectSyncSegments(this.root, segments, mergeableFilter);
     }
     return { segments };
   }
 }
 
 /** Recursively collect sync segment paths from the tree */
-function collectSyncSegments(node: SegmentNode, out: string[]): void {
-  if (!node.isAsync) {
+function collectSyncSegments(
+  node: SegmentNode,
+  out: string[],
+  mergeableFilter?: Set<string>
+): void {
+  if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) {
     out.push(node.segment);
   }
   for (const child of node.children.values()) {
-    collectSyncSegments(child, out);
+    collectSyncSegments(child, out, mergeableFilter);
   }
 }
 

package/src/client/segment-context.ts

@@ -37,6 +37,13 @@ export function useSegmentContext(): SegmentContextValue | null {
 
 interface SegmentProviderProps {
   segments: string[];
+  /**
+   * Unique identifier for this segment, used by the client-side segment
+   * merger for element caching. For route groups this includes the group
+   * name (e.g., "/(marketing)") since groups share their parent's urlPath.
+   * Falls back to the reconstructed path from `segments` if not provided.
+   */
+  segmentId?: string;
   parallelRouteKeys: string[];
   children: React.ReactNode;
 }
@@ -45,7 +52,7 @@ interface SegmentProviderProps {
  * Wraps each layout to provide segment position context.
  * Injected by rsc-entry.ts during element tree construction.
  */
-export function SegmentProvider({ segments, parallelRouteKeys, children }: SegmentProviderProps) {
+export function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }: SegmentProviderProps) {
   const value = useMemo(
     () => ({ segments, parallelRouteKeys }),
     // segments and parallelRouteKeys are static per layout — they don't change

package/src/client/segment-merger.ts

@@ -34,6 +34,13 @@ export interface CachedSegmentEntry {
   segmentPath: string;
   /** The SegmentProvider element for this segment */
   element: ReactElement;
+  /**
+   * Whether this segment's cached element contains a nested SegmentProvider.
+   * Only segments with inner SegmentProviders are safe to skip — the merger
+   * can only replace inner SegmentProviders, not pages embedded in layout output.
+   * Used by the state tree serialization to exclude non-mergeable segments.
+   */
+  hasMergeableChild: boolean;
 }
 
 // ─── Segment Element Cache ───────────────────────────────────────
@@ -64,6 +71,29 @@ export class SegmentElementCache {
   get size(): number {
     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(): Set<string> {
+    const paths = new Set<string>();
+    for (const [, entry] of this.entries) {
+      if (entry.hasMergeableChild) {
+        paths.add(entry.segmentPath);
+      }
+    }
+    return paths;
+  }
 }
 
 // ─── SegmentProvider Detection ───────────────────────────────────
@@ -81,12 +111,16 @@ export 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("/").
+ *
+ * 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.
  */
 export function getSegmentPath(element: ReactElement): string {
-  const segments = (element.props as { segments: string[] }).segments;
-  const filtered = segments.filter(Boolean);
+  const props = element.props as { segments: string[]; segmentId?: string };
+  // segmentId is the authoritative key — includes group name for route groups
+  if (props.segmentId) return props.segmentId;
+  const filtered = props.segments.filter(Boolean);
   return filtered.length === 0 ? '/' : '/' + filtered.join('/');
 }
 
@@ -102,6 +136,12 @@ export function getSegmentPath(element: ReactElement): string {
 export function extractSegments(element: unknown): CachedSegmentEntry[] {
   const segments: CachedSegmentEntry[] = [];
   walkForSegments(element, segments);
+  // Compute hasMergeableChild: a segment is mergeable if there's another
+  // SegmentProvider nested below it. The segments list is ordered outermost
+  // to innermost, so each segment's child is the next entry.
+  for (let i = 0; i < segments.length; i++) {
+    segments[i].hasMergeableChild = i < segments.length - 1;
+  }
   return segments;
 }
 
@@ -117,6 +157,7 @@ function walkForSegments(node: unknown, out: CachedSegmentEntry[]): void {
     out.push({
       segmentPath: getSegmentPath(el),
       element: el,
+      hasMergeableChild: false, // computed after collection in extractSegments
     });
     // Continue walking into children to find nested segments
     walkChildren(props.children as ReactNode, out);
@@ -224,9 +265,16 @@ export function replaceInnerSegment(
   const path = findSegmentProviderPath(cachedElement, innerSegmentPath);
 
   if (!path || path.length === 0) {
-    // No inner SegmentProvider found — the cached element's children
-    // IS the leaf content. Replace children directly.
-    return cloneElement(cachedElement, {}, newInnerContent);
+    // No inner SegmentProvider found — this segment's cached element
+    // wraps a page directly (no child layout with a SegmentProvider).
+    // We CANNOT safely replace the page because it's embedded deep in
+    // the layout's server-rendered output tree and we don't know its
+    // position. Return the cached element unchanged as a safety fallback.
+    //
+    // The server should not skip segments without a child layout below
+    // them (enforced by hasRenderedLayoutBelow in buildRouteElement).
+    // If this codepath is reached, it indicates a server/client mismatch.
+    return cachedElement;
   }
 
   // Reconstruct bottom-up: replace the innermost element first, then

package/src/server/route-element-builder.ts

@@ -326,6 +326,16 @@ export async function buildRouteElement(
   // client navigation), sync layouts the client already has are skipped.
   // Access.ts already ran for ALL segments in the pre-render loop above.
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  //
+  // hasRenderedLayoutBelow tracks whether a non-skipped layout has been
+  // seen below the current segment. A segment can ONLY be skipped if
+  // there is a rendered layout below it — the client merger can only
+  // replace inner SegmentProviders (client component boundaries), not
+  // page content embedded in a layout's server-rendered output.
+  // Without this guard, skipping the innermost layout causes the merger
+  // to drop the layout entirely and replace it with just the page.
+  let hasRenderedLayoutBelow = false;
+
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
     const isLeaf = i === segments.length - 1;
@@ -334,12 +344,22 @@ export async function buildRouteElement(
     // Check if this segment's layout can be skipped for partial rendering.
     // Skipped segments: no layout wrapping, no error boundaries, no slots,
     // no AccessGate in element tree (access already ran pre-render).
-    const skip = shouldSkipSegment(
-      segment.urlPath,
-      layoutComponent,
-      isLeaf,
-      clientStateTree ?? null
-    );
+    //
+    // Additional constraints beyond shouldSkipSegment:
+    // - Must have a rendered layout below (so the merger can find an
+    //   inner SegmentProvider to splice the new content into)
+    // - Route groups are never skipped because sibling groups share the
+    //   same urlPath (e.g., /(marketing) and /(app) both have "/"),
+    //   which would cause the wrong cached layout to be reused
+    const skip =
+      shouldSkipSegment(
+        segment.urlPath,
+        layoutComponent,
+        isLeaf,
+        clientStateTree ?? null
+      ) &&
+      hasRenderedLayoutBelow &&
+      segment.segmentType !== 'group';
 
     if (skip) {
       // Skip this segment entirely — the client uses its cached version.
@@ -350,6 +370,12 @@ export async function buildRouteElement(
       continue;
     }
 
+    // This segment is rendered — mark that future (outer) segments have
+    // a rendered layout below them and can safely be skipped.
+    if (layoutComponent) {
+      hasRenderedLayoutBelow = true;
+    }
+
     // Wrap with error boundaries from this segment (inside layout).
     element = await wrapSegmentWithErrorBoundaries(segment, element, h);
 
@@ -407,8 +433,18 @@ export async function buildRouteElement(
         );
       };
 
+      // segmentId uniquely identifies this segment for client-side element
+      // caching. For route groups, urlPath is shared with the parent (both "/"),
+      // so we include the group name to distinguish them. Without this, the
+      // segment merger's element cache would conflate root and group elements.
+      const segmentId =
+        segment.segmentType === 'group'
+          ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
+          : segment.urlPath;
+
       element = h(SegmentProvider, {
         segments: segmentPath,
+        segmentId,
         parallelRouteKeys,
         children: h(TracedLayout, {
           ...slotProps,

package/src/server/state-tree-diff.ts

@@ -55,23 +55,23 @@ export function parseClientStateTree(req: Request): Set<string> | null {
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
 export function shouldSkipSegment(
-  urlPath: string,
-  layoutComponent: ((...args: unknown[]) => unknown) | undefined,
-  isLeaf: boolean,
-  clientSegments: Set<string> | null
+  _urlPath: string,
+  _layoutComponent: ((...args: unknown[]) => unknown) | undefined,
+  _isLeaf: boolean,
+  _clientSegments: Set<string> | null
 ): boolean {
-  // No state tree → full render (initial load, refresh, etc.)
-  if (!clientSegments) return false;
-
-  // Leaf segments (pages) are never skipped
-  if (isLeaf) return false;
-
-  // No layout → nothing to skip
-  if (!layoutComponent) return false;
-
-  // Async layouts always re-render (they may depend on request context)
-  if (layoutComponent.constructor?.name === 'AsyncFunction') return false;
-
-  // Skip if the client already has this segment cached
-  return clientSegments.has(urlPath);
+  // DISABLED: Client-side segment merging via React element tree walking
+  // is too fragile for production. The merger's replaceInnerSegment relies
+  // on walking RSC-decoded element trees to find SegmentProvider boundaries,
+  // but production trees contain structures the walker can't handle:
+  // Suspense wrappers, error boundaries, AccessGate components, React lazy
+  // refs, and client component module references.
+  //
+  // The merger infrastructure (segment-merger.ts, element cache, state tree
+  // filtering) is in place and tested. Re-enable when the merger can handle
+  // real RSC element trees — likely requires a SegmentOutlet client component
+  // approach instead of post-hoc element tree walking.
+  //
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  return false;
 }