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

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.125",
   "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,7 +19,7 @@
 // - searchParams and inline query string are mutually exclusive
 
 import {
-  useOptimistic,
+  useState,
   useEffect,
   useRef,
   type AnchorHTMLAttributes,
@@ -501,16 +501,22 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   } = props as LinkRuntimeProps;
   const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
 
-  // ─── Per-link pending state (useOptimistic) ────────────────────────
+  // ─── Per-link pending state ─────────────────────────────────────────
   // 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.
+  // Link click stores the instance; NavigationRoot activates as an
+  // urgent update (outside startTransition) so the pending state
+  // shows immediately. resetLinkPending() inside the transition
+  // commits atomically with the new tree.
+  //
+  // Uses useState (not useOptimistic) to avoid TIM-964: useOptimistic
+  // setters inside async startTransition + await decodePromise
+  // trigger "Rendered more hooks" when two navigations overlap
+  // under the Navigation API.
   //
   // See design/19-client-navigation.md §"Per-Link Pending State"
-  const [linkStatus, setIsPending] = useOptimistic(LINK_IDLE);
+  const [linkStatus, setIsPending] = useState(LINK_IDLE);
 
   // Build the link instance ref for the pending store.
   // The ref is stable across renders — we update the setter on each

package/src/client/navigation-root.tsx

@@ -132,7 +132,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,7 +197,10 @@ 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>) => {
+  _navigateTransition = (
+    url: string,
+    perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>
+  ) => {
     // Urgent: show pending state immediately (for TopLoader / usePendingNavigation)
     setPendingUrl(url);
 
@@ -204,29 +210,42 @@ export function NavigationRoot({
     const counter = getTransitionCounter();
     const transId = ++counter.id;
 
+    // Activate per-link pending state as an URGENT update (outside
+    // startTransition). With useState (not useOptimistic), this commits
+    // immediately so the clicked link shows pending before the next paint.
+    // The corresponding resetLinkPending() is called INSIDE the transition
+    // so it commits atomically with the new tree.
+    //
+    // CRITICAL: activateLinkPending must NOT be called inside the
+    // startTransition that awaits decodePromise. With useOptimistic,
+    // that combination triggers "Rendered more hooks" when two
+    // navigations overlap under the Navigation API (TIM-964).
+    activateLinkPending();
+
     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();
         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);
+          // Await RSC stream completion inside the transition so the
+          // link's pending state (set urgently above) persists until
+          // the full payload is consumed. resetLinkPending() below
+          // commits atomically with the new tree when the transition
+          // settles — no frame where pending=false but old content shows.
+          if (decodePromise) await decodePromise;
           if (counter.id === transId) {
-            setElement(newElement);
+            resetLinkPending();
             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();
@@ -297,7 +316,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 +354,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);
   };
 }