@timber-js/app 0.2.0-alpha.124 → 0.2.0-alpha.126

package/dist/server/pipeline-outcome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-outcome.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgBH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAE1D,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAID;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,QAAQ,CAAC,CAgHnB"}
+{"version":3,"file":"pipeline-outcome.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgBH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAchE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAE1D,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAID;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,QAAQ,CAAC,CA2HnB"}

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;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAY9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAa7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAezD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAM7D;AAID;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAID,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;;;;;;;GAOG;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;AA8DD;;;;;;;;;;;;;GAaG;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,EACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,OAAO,CAAC,kBAAkB,CAAC,CA0Y7B"}
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAY9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAc7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAuCzD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAM7D;AAID;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAID,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;;;;;;;GAOG;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;AA8DD;;;;;;;;;;;;;GAaG;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,EACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,OAAO,CAAC,kBAAkB,CAAC,CAob7B"}

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

@@ -83,6 +83,7 @@ export declare function buildSegmentInfo(segments: ManifestSegmentNode[], layout
     segment: ManifestSegmentNode;
 }>): Array<{
     path: string;
+    segmentId?: string;
     isAsync: boolean;
 }>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,IAAI;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAQ/F;AAID;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,yDAAyD;IACzD,gBAAgB,IAAI,MAAM,CAAC;IAC3B,yEAAyE;IACzE,aAAa,IAAI,mBAAmB,EAAE,CAAC;CACxC;AAED,wBAAgB,2BAA2B,IAAI,qBAAqB,CAkCnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,EAAE,CA8ClE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,KAAK,CAAC;IACtB,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC,GACD,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA0B3C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGzD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,cAAc,EACtB,eAAe,EAAE,OAAO,GACvB,QAAQ,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIpD;AAGD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAW1E"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,IAAI;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAQ/F;AAID;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,yDAAyD;IACzD,gBAAgB,IAAI,MAAM,CAAC;IAC3B,yEAAyE;IACzE,aAAa,IAAI,mBAAmB,EAAE,CAAC;CACxC;AAED,wBAAgB,2BAA2B,IAAI,qBAAqB,CAkCnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,EAAE,CA8ClE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,KAAK,CAAC;IACtB,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC,GACD,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA8B/D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGzD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,cAAc,EACtB,eAAe,EAAE,OAAO,GACvB,QAAQ,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIpD;AAGD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAW1E"}

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

@@ -27,17 +27,24 @@ export declare function parseClientStateTree(req: Request): Set<string> | null;
  * Determine whether a segment's layout rendering can be skipped.
  *
  * A segment is skipped when ALL of the following are true:
- * 1. The client has the segment in its state tree (clientSegments contains urlPath)
- * 2. The layout is sync (not an async function — async layouts always re-render)
- * 3. The segment is NOT the leaf (pages are never cached across navigations)
+ * 1. The client sent a state tree (clientSegments is non-null)
+ * 2. The client has this segment cached (clientSegments contains urlPath)
+ * 3. The segment has a layout (otherwise nothing to skip)
+ * 4. The layout is sync (not an async function — async layouts may depend
+ *    on per-request data and must always re-render)
+ * 5. The segment is NOT the leaf (pages are never cached across navigations)
+ *
+ * Additional constraints enforced by the caller (buildRouteElement):
+ * - Must have a rendered layout below (so SegmentOutlet has content to show)
+ * - Route groups are never skipped (siblings share urlPath)
  *
  * Access.ts still runs for skipped segments — this is enforced by the caller
- * (buildRouteElement) which runs all access checks before building the tree.
+ * which wraps with AccessGate regardless of skip status.
  *
  * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
  * @param layoutComponent - The loaded layout component function
  * @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;AAIH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAcrE;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"}
+{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAcrE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,CAYT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.124",
+  "version": "0.2.0-alpha.126",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry/hydrate.ts

@@ -25,6 +25,7 @@ import {
   getNavigationState,
   setNavigationState,
 } from '../navigation-context.js';
+import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.js';
 import { TimberNuqsAdapter } from '../nuqs-adapter.js';
 import { isPageUnloading } from '../unload-guard.js';
 import { NavigationRoot, installDeferredNavigation } from '../navigation-root.js';
@@ -89,7 +90,12 @@ export function hydrateApp({ rscResult, config }: HydrateOptions): void {
       { value: navState },
       element as React.ReactNode
     );
-    const wrapped = createElement(TimberNuqsAdapter, null, withNav);
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
     const rootElement = createElement(NavigationRoot, {
       initial: wrapped,
       topLoaderConfig: config.topLoader,

package/src/client/browser-entry/index.ts

@@ -81,7 +81,9 @@ function bootstrap(runtimeConfig: typeof config): void {
   const rscResult = createRscPayloadStream();
 
   // Step 3: Create router + Navigation API integration
-  const { router, navApiController } = createTimberRouter();
+  const { router, navApiController } = createTimberRouter({
+    initialElement: rscResult?.element ?? undefined,
+  });
 
   // Step 4: Pre-hydration — set params + navigation state (MUST run after router init)
   runPreHydration();

package/src/client/browser-entry/post-hydration.ts

@@ -58,19 +58,6 @@ export function setupPostHydration({
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
 
-  // Cache segment elements from the initial RSC payload after hydration.
-  // The element from createFromReadableStream is a Flight thenable that
-  // React resolves during hydration. Once resolved (status='fulfilled'),
-  // its .value contains the React element tree we can walk.
-  // Use requestAnimationFrame to run after hydration commits.
-  if (initialElement != null) {
-    requestAnimationFrame(() => {
-      const el = initialElement as { status?: string; value?: unknown };
-      const resolved = el.status === 'fulfilled' && el.value != null ? el.value : initialElement;
-      router.cacheElementTree(resolved);
-    });
-  }
-
   // If the hydration path was skipped (no RSC payload), populate the
   // fallback params from server embed here.
   const lateTimberParams = (self as unknown as Record<string, unknown>).__timber_params;

package/src/client/browser-entry/router-init.ts

@@ -16,6 +16,7 @@ import { applyHeadElements } from '../head.js';
 import { TimberNuqsAdapter } from '../nuqs-adapter.js';
 import { NavigationProvider } from '../navigation-context.js';
 import { transitionRender, navigateTransition } from '../navigation-root.js';
+import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.js';
 import { isStaleClientReference, triggerStaleReload } from '../stale-reload.js';
 import {
   hasNavigationApi,
@@ -24,6 +25,10 @@ import {
 } from '../navigation-api.js';
 import { getScrollY } from './scroll.js';
 
+export interface RouterInitOptions {
+  initialElement?: unknown;
+}
+
 export interface RouterInitResult {
   router: RouterInstance;
   navApiController: NavigationApiController | null;
@@ -36,12 +41,20 @@ export interface RouterInitResult {
  * the initial render (methods lazily resolve the router at invocation,
  * not render time, but initRouter must still run first).
  */
-export function createTimberRouter(): RouterInitResult {
+export function createTimberRouter(options?: RouterInitOptions): RouterInitResult {
   // Feature-detect Navigation API. When available, the navigate event
   // replaces popstate for back/forward and catches external navigations.
   // See design/19-client-navigation.md §"Navigation API Integration"
   const useNavApi = hasNavigationApi();
 
+  // Track the current unwrapped RSC payload. On partial navigation, the
+  // router re-wraps this same element with new NavigationProvider context
+  // so mounted SegmentOutlets are preserved (they pick up changes via
+  // SegmentUpdateContext, not from new children props).
+  // Initialized from the hydration element so partial nav works on the
+  // very first client navigation (before any wrapPayload call).
+  let currentPayload: unknown = options?.initialElement ?? null;
+
   const deps: RouterDeps = {
     fetch: (url, init) => window.fetch(url, init),
     pushState: (data, unused, url) => window.history.pushState(data, unused, url),
@@ -75,20 +88,14 @@ export function createTimberRouter(): RouterInitResult {
     // reference module IDs that don't exist in the old client bundle.
     // We catch "Could not find the module" errors and trigger a full
     // page reload so the browser fetches the new bundle.
-    decodeRsc: async (fetchPromise: Promise<Response>) => {
+    // Pass the fetch promise directly to createFromFetch for streaming.
+    // React progressively renders chunks via Suspense as they arrive.
+    // The transition stays open via decodePromise (awaited inside
+    // startTransition) so useOptimistic pending state persists for
+    // the full stream duration.
+    decodeRsc: (fetchPromise: Promise<Response>) => {
       try {
-        // Wait for the full RSC stream to arrive before decoding.
-        // createFromFetch resolves on the first Flight chunk (the shell),
-        // but we need the transition to stay pending for the full response
-        // so useOptimistic (per-link pending) persists during slow navigations.
-        // Buffer the complete response, then decode from the buffered stream.
-        const response = await fetchPromise;
-        const body = await response.arrayBuffer();
-        const buffered = new Response(body, {
-          headers: response.headers,
-          status: response.status,
-        });
-        return await createFromFetch(Promise.resolve(buffered));
+        return createFromFetch(fetchPromise);
       } catch (error) {
         if (isStaleClientReference(error)) {
           triggerStaleReload();
@@ -114,7 +121,12 @@ export function createTimberRouter(): RouterInitResult {
         { value: navState },
         element as React.ReactNode
       );
-      const wrapped = createElement(TimberNuqsAdapter, null, withNav);
+      const withUpdates = createElement(
+        SegmentUpdateContext.Provider,
+        { value: EMPTY_SEGMENT_UPDATES },
+        withNav
+      );
+      const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
       transitionRender(wrapped);
     },
 
@@ -128,18 +140,32 @@ export function createTimberRouter(): RouterInitResult {
     // is passed explicitly by the router — no getNavigationState() needed.
     navigateTransition: (pendingUrl: string, perform) => {
       return navigateTransition(pendingUrl, async () => {
-        const payload = await perform((rawPayload: unknown, navState: NavigationState) => {
-          const withNav = createElement(
-            NavigationProvider,
-            { value: navState },
-            rawPayload as React.ReactNode
-          );
-          return createElement(TimberNuqsAdapter, null, withNav);
-        });
-        return payload as React.ReactNode;
+        const { element, decodePromise } = await perform(
+          (
+            rawPayload: unknown,
+            navState: NavigationState,
+            segmentUpdates?: Map<string, unknown>
+          ) => {
+            currentPayload = rawPayload;
+            const withNav = createElement(
+              NavigationProvider,
+              { value: navState },
+              rawPayload as React.ReactNode
+            );
+            const withUpdates = createElement(
+              SegmentUpdateContext.Provider,
+              { value: (segmentUpdates ?? EMPTY_SEGMENT_UPDATES) as Map<string, React.ReactNode> },
+              withNav
+            );
+            return createElement(TimberNuqsAdapter, null, withUpdates);
+          }
+        );
+        return { element: element as React.ReactNode, decodePromise };
       });
     },
 
+    _getCurrentPayload: () => currentPayload,
+
     // Schedule a callback after the next paint so scroll operations
     // happen after React commits the new content to the DOM.
     // Double-rAF ensures the browser has painted the new frame.

package/src/client/link-pending-store.ts

@@ -1,17 +1,17 @@
 /**
- * Link Pending Store — per-link optimistic pending state.
+ * Link Pending Store — per-link pending state.
  *
  * Tracks which link instance is currently navigating so that only the
- * clicked link shows pending. Uses `useOptimistic` from React 19 —
- * the optimistic value (isPending=true) is set inside NavigationRoot's
- * async startTransition so it persists for the duration of the RSC
- * fetch, then auto-reverts to idle when the transition settles.
+ * clicked link shows pending. Uses useState in Link — the pending
+ * state is set as an urgent update (outside startTransition) so it
+ * shows immediately, then reset inside the transition so it commits
+ * atomically with the new tree.
  *
  * Flow:
  * 1. Link click → setLinkForCurrentNavigation(instance) stores the ref
- * 2. NavigationRoot startTransition → activateLinkPending() calls
- *    instance.setIsPending(LINK_PENDING) inside the async transition
- * 3. Transition settles → useOptimistic auto-reverts to LINK_IDLE
+ * 2. NavigationRoot → activateLinkPending() calls
+ *    instance.setIsPending(LINK_PENDING) as an urgent update
+ * 3. Inside startTransition → resetLinkPending() commits with new tree
  *
  * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys because
  * the RSC client bundler can duplicate this module across chunks.
@@ -52,21 +52,25 @@ function getStore(): { current: LinkPendingInstance | null } {
 /**
  * Register the link instance that initiated the current navigation.
  * Called from Link's click handler. Does NOT call setIsPending —
- * that happens inside NavigationRoot's startTransition via
- * activateLinkPending().
+ * that happens via activateLinkPending() called from NavigationRoot.
  *
- * Resets the previous link to idle immediately (the old link's
- * useOptimistic reverts since its transition already settled).
+ * Resets the previous link to idle immediately if a different link
+ * is being registered (handles overlapping link clicks).
  */
 export function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {
   const store = getStore();
+  if (store.current && store.current !== link) {
+    store.current.setIsPending(LINK_IDLE);
+  }
   store.current = link;
 }
 
 /**
  * Activate pending state on the current link instance.
- * MUST be called inside NavigationRoot's async startTransition —
- * this is what makes useOptimistic persist for the navigation duration.
+ * Called as an urgent update (outside startTransition) so the link
+ * shows pending immediately. The corresponding resetLinkPending()
+ * is called inside the transition so it commits atomically with
+ * the new tree.
  */
 export function activateLinkPending(): void {
   const store = getStore();
@@ -74,9 +78,10 @@ export function activateLinkPending(): void {
 }
 
 /**
- * Reset the current link's pending state. With useOptimistic this is
- * handled automatically when the transition settles. Kept for callers
- * that explicitly need to clear on error paths.
+ * Reset the current link's pending state and clear the store.
+ * Call inside startTransition so the reset commits atomically
+ * with the new tree (no frame where pending=false but old content
+ * is still visible).
  */
 export function resetLinkPending(): void {
   const store = getStore();

package/src/client/link.tsx

@@ -19,9 +19,7 @@
 // - searchParams and inline query string are mutually exclusive
 
 import {
-  useOptimistic,
-  useEffect,
-  useRef,
+  useTransition,
   type AnchorHTMLAttributes,
   type ReactNode,
   type MouseEvent as ReactMouseEvent,
@@ -34,15 +32,11 @@ import { LinkStatusContext } from './use-link-status.js';
 import { getRouterOrNull } from './router-ref.js';
 import { getSsrData } from './ssr-data.js';
 import { mergePreservedSearchParams } from '../shared/merge-search-params.js';
-import {
-  setLinkForCurrentNavigation,
-  unmountLinkForCurrentNavigation,
-  LINK_IDLE,
-  type LinkPendingInstance,
-} from './link-pending-store.js';
-import { setNavLinkMetadata } from './nav-link-store.js';
-import { hasNavigationApi } from './navigation-api.js';
 import { getLinkCodec } from '../params/codec-registry.js';
+import type { LinkStatus } from './use-link-status.js';
+
+const LINK_PENDING: LinkStatus = { isPending: true };
+const LINK_IDLE: LinkStatus = { isPending: false };
 
 // ─── Current Search Params ────────────────────────────────────────
 
@@ -501,37 +495,13 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   } = props as LinkRuntimeProps;
   const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
 
-  // ─── Per-link pending state (useOptimistic) ────────────────────────
-  // Each Link has its own pending state. Only the clicked link's
-  // setter is invoked during navigation — zero other links re-render.
-  //
-  // Link click stores the instance; NavigationRoot activates inside startTransition.
-  // useOptimistic auto-reverts to LINK_IDLE when the navigation
-  // startTransition — batched with the new tree commit.
-  //
-  // See design/19-client-navigation.md §"Per-Link Pending State"
-  const [linkStatus, setIsPending] = useOptimistic(LINK_IDLE);
-
-  // Build the link instance ref for the pending store.
-  // The ref is stable across renders — we update the setter on each
-  // render to keep it current.
-  const linkInstanceRef = useRef<LinkPendingInstance | null>(null);
-  if (!linkInstanceRef.current) {
-    linkInstanceRef.current = { setIsPending };
-  } else {
-    linkInstanceRef.current.setIsPending = setIsPending;
-  }
-
-  // Clean up if this link unmounts while it's the current navigation link.
-  // Prevents calling setOptimistic on an unmounted component.
-  useEffect(() => {
-    const instance = linkInstanceRef.current;
-    return () => {
-      if (instance) {
-        unmountLinkForCurrentNavigation(instance);
-      }
-    };
-  }, []);
+  // ─── Per-link pending state ─────────────────────────────────────────
+  // Each Link owns a useTransition. On click, it wraps
+  // router.navigate() in startTransition — only this Link re-renders
+  // for isPending, zero siblings touched. The transition tracks the
+  // full navigation lifecycle (fetch + render + commit).
+  const [isPending, startTransition] = useTransition();
+  const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
 
   // Preserve search params from the current URL when requested.
   // useSearchParams() works during both SSR (reads from request context)
@@ -571,49 +541,30 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         }
 
         const router = getRouterOrNull();
-        if (!router) return; // SSR or pre-hydration — fall through to browser nav
+        if (!router) return;
 
-        const shouldScroll = scroll !== false;
+        const navHref = preserveSearchParams
+          ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+          : resolvedHref;
 
-        // Register this link in the pending store. The actual
-        // setIsPending(LINK_PENDING) call happens inside NavigationRoot's
-        // async startTransition via activateLinkPending().
-
-        setLinkForCurrentNavigation(linkInstanceRef.current);
-
-        // When Navigation API is active, let the <a> click propagate
-        // naturally — do NOT call preventDefault(). The navigate event
-        // handler intercepts it and runs the RSC pipeline. This is a
-        // user-initiated navigation, so Chrome shows the native loading
-        // indicator (tab spinner). Metadata (scroll, link instance) is
-        // passed via nav-link-store so the handler can configure the nav.
-        //
-        // Without Navigation API (fallback), preventDefault and drive
-        // navigation through the router as before.
-        if (hasNavigationApi()) {
-          setNavLinkMetadata({
-            scroll: shouldScroll,
-            linkInstance: linkInstanceRef.current,
-          });
-          // Don't preventDefault — let the <a> click fire the navigate event
+        const resolved = new URL(navHref, window.location.href);
+
+        if (
+          resolved.pathname === window.location.pathname &&
+          resolved.search === window.location.search &&
+          resolved.hash
+        ) {
           return;
         }
 
-        // Hash-only hrefs — let the browser handle scroll-to-anchor natively.
-        // The Navigation API path already skips these via event.hashChange;
-        // this covers the fallback (Safari/Firefox) where we drive navigation manually.
-        if (resolvedHref.startsWith('#')) return;
-
-        // History API fallback — prevent default and navigate via router
         event.preventDefault();
 
-        // Re-merge preserved search params at click time to pick up any
-        // URL changes since render (e.g. from other navigations or pushState).
-        const navHref = preserveSearchParams
-          ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
-          : resolvedHref;
+        const shouldScroll = scroll !== false;
+        const absoluteHref = resolved.pathname + resolved.search;
 
-        void router.navigate(navHref, { scroll: shouldScroll });
+        startTransition(async () => {
+          await router.navigate(absoluteHref, { scroll: shouldScroll });
+        });
       }
     : userOnClick; // External links — just pass through user's onClick
 
@@ -624,11 +575,11 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
           userOnMouseEnter?.(event);
           const router = getRouterOrNull();
           if (router) {
-            // Re-merge preserved search params at hover time for fresh prefetch URL
             const prefetchHref = preserveSearchParams
               ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
               : resolvedHref;
-            router.prefetch(prefetchHref);
+            const resolved = new URL(prefetchHref, window.location.href);
+            router.prefetch(resolved.pathname + resolved.search);
           }
         }
       : userOnMouseEnter;

package/src/client/nav-link-store.ts

@@ -2,26 +2,16 @@
  * Navigation Link Store — passes per-link metadata from Link's onClick
  * to the Navigation API's navigate event handler.
  *
- * When the Navigation API is active, Link does NOT call event.preventDefault()
- * or router.navigate(). Instead it stores metadata (scroll option, link
- * pending instance) here, and lets the <a> click propagate naturally.
- * The navigate event handler reads this metadata to configure the RSC
- * navigation with the correct options.
- *
- * This store is consumed once per navigation — after reading, the metadata
- * is cleared. If no metadata is present (e.g., a plain <a> tag without
- * our Link component), the navigate handler uses default options.
+ * Used for external navigations (plain <a> tags intercepted by the
+ * Navigation API). Link components drive navigation directly via
+ * router.navigate() and don't use this store.
  *
  * See design/19-client-navigation.md §"Navigation API Integration"
  */
 
-import type { LinkPendingInstance } from './link-pending-store.js';
-
 export interface NavLinkMetadata {
   /** Whether to scroll to top after navigation. Default: true. */
   scroll: boolean;
-  /** The Link's pending state instance for per-link status tracking. */
-  linkInstance: LinkPendingInstance | null;
 }
 
 let pendingMetadata: NavLinkMetadata | null = null;

package/src/client/navigation-root.tsx

@@ -32,7 +32,6 @@
  */
 
 import { createElement, Fragment, startTransition, useState, type ReactNode } from 'react';
-import { activateLinkPending, resetLinkPending } from './link-pending-store.js';
 import { PendingNavigationProvider } from './navigation-context.js';
 import { TopLoader, type TopLoaderConfig } from './top-loader.js';
 
@@ -132,7 +131,10 @@ let _transitionRender: ((element: ReactNode) => void) | null = null;
  * with the pending URL.
  */
 let _navigateTransition:
-  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => Promise<void>)
+  | ((
+      pendingUrl: string,
+      perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>
+    ) => Promise<void>)
   | null = null;
 
 // ─── Component ───────────────────────────────────────────────────
@@ -194,42 +196,42 @@ export function NavigationRoot({
   // are deferred. When the transition commits, the new tree and pendingUrl=null
   // both apply in the same React commit — making the pending→active transition
   // atomic (no frame where pending is false but the old tree is still visible).
-  _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately (for TopLoader / usePendingNavigation)
-    setPendingUrl(url);
-
+  _navigateTransition = (
+    url: string,
+    perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>
+  ) => {
     // Increment the transition counter SYNCHRONOUSLY (before startTransition
     // schedules the async work). Each call gets a unique transId; the counter
     // is the same globalThis singleton, so a newer call always has a higher id.
     const counter = getTransitionCounter();
     const transId = ++counter.id;
 
+    // NO urgent setPendingUrl here. Per-link pending state is driven by
+    // Link's own useTransition — only the clicked Link re-renders for
+    // isPending. setPendingUrl is set INSIDE startTransition so the
+    // TopLoader activates as a transition update (no full-tree re-render).
+
     return new Promise<void>((resolve, reject) => {
       startTransition(async () => {
-        // Activate per-link pending state inside this async transition.
-        // useOptimistic persists the isPending=true value for the duration
-        // of this transition, then auto-reverts when it settles.
-        activateLinkPending();
+        setPendingUrl(url);
         try {
-          const newElement = await perform();
-          // Only commit state if this is still the active navigation.
-          // A superseded transition's updates must be dropped entirely.
+          const { element, decodePromise } = await perform();
+          if (counter.id !== transId) {
+            decodePromise?.catch(() => {});
+            reject(new DOMException('Navigation superseded', 'AbortError'));
+            return;
+          }
+          setElement(element);
+          if (decodePromise) await decodePromise;
           if (counter.id === transId) {
-            setElement(newElement);
             setPendingUrl(null);
             resolve();
           } else {
-            // Stale transition — a newer navigation has superseded this one.
-            // Reject so the caller (navigate/refresh/handlePopState) doesn't
-            // run post-transition side effects (applyHead, scroll, event
-            // dispatch) with stale data. All callers catch AbortError.
             reject(new DOMException('Navigation superseded', 'AbortError'));
           }
         } catch (err) {
-          // Only clear pending if this is still the active navigation.
           if (counter.id === transId) {
             setPendingUrl(null);
-            resetLinkPending();
           }
           reject(err);
         }
@@ -297,7 +299,7 @@ export function transitionRender(element: ReactNode): void {
  */
 export function navigateTransition(
   pendingUrl: string,
-  perform: () => Promise<ReactNode>
+  perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>
 ): Promise<void> {
   if (_navigateTransition) {
     return _navigateTransition(pendingUrl, perform);
@@ -335,8 +337,11 @@ export function installDeferredNavigation(createAndMount: (initial: ReactNode) =
   _transitionRender = (element: ReactNode) => {
     mountOnce(element);
   };
-  _navigateTransition = async (_pendingUrl: string, perform: () => Promise<ReactNode>) => {
-    const element = await perform();
+  _navigateTransition = async (
+    _pendingUrl: string,
+    perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>
+  ) => {
+    const { element } = await perform();
     mountOnce(element);
   };
 }