@timber-js/app 0.1.30 → 0.1.31

package/dist/client/router.d.ts

@@ -43,6 +43,18 @@ export interface RouterDeps {
     afterPaint?: (callback: () => void) => void;
     /** Apply resolved head elements (title, meta tags) to the DOM after navigation. */
     applyHead?: (elements: HeadElement[]) => void;
+    /**
+     * Run a navigation inside a React transition with optimistic pending URL.
+     * The pending URL shows immediately (useOptimistic urgent update) and
+     * reverts when the transition commits (atomic with the new tree).
+     *
+     * The `perform` callback receives a `wrapPayload` function to wrap the
+     * decoded RSC payload with NavigationProvider + NuqsAdapter before
+     * TransitionRoot sets it as the new element.
+     *
+     * If not provided (tests), the router falls back to renderRoot.
+     */
+    navigateTransition?: (pendingUrl: string, perform: (wrapPayload: (payload: unknown) => unknown) => Promise<unknown>) => Promise<void>;
 }
 export interface RouterInstance {
     /** Navigate to a new URL (forward navigation) */

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/transition-root.d.ts

@@ -11,41 +11,61 @@
  * a transition update. React keeps the old committed tree visible while
  * any new Suspense boundaries in the transition resolve.
  *
- * This is the client-side equivalent of deferSuspenseFor on the server:
- * the old content stays visible until the new content is ready, avoiding
- * flash-of-fallback during fast navigations.
+ * Also manages `pendingUrl` via `useOptimistic`. During a navigation
+ * transition, the optimistic value (the target URL) shows immediately
+ * while the transition is pending, and automatically reverts to null
+ * when the transition commits. This ensures useLinkStatus and
+ * useNavigationPending show the pending state immediately and clear
+ * atomically with the new tree — same pattern Next.js uses with
+ * useOptimistic per Link instance, adapted for timber's server-component
+ * Link with global click delegation.
  *
  * See design/05-streaming.md §"deferSuspenseFor"
+ * See design/19-client-navigation.md §"NavigationContext"
  */
 import { type ReactNode } from 'react';
 /**
  * Root wrapper component that enables transition-based rendering.
  *
- * Renders no DOM elements — returns the current element directly.
- * This means the DOM tree matches the server-rendered HTML during
- * hydration (TransitionRoot is invisible to the DOM).
+ * Renders PendingNavigationProvider around children for the pending URL
+ * context. The DOM tree matches the server-rendered HTML during hydration
+ * (the provider renders no extra DOM elements).
  *
  * Usage in browser-entry.ts:
  *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
  *   reactRoot = hydrateRoot(document, rootEl);
  *
  * Subsequent navigations:
+ *   navigateTransition(url, async () => { fetch; return wrappedElement; });
+ *
+ * Non-navigation renders:
  *   transitionRender(newWrappedElement);
  */
 export declare function TransitionRoot({ initial }: {
     initial: ReactNode;
 }): ReactNode;
 /**
- * Trigger a transition render. React keeps the old committed tree
- * visible while any new Suspense boundaries in the update resolve.
- *
- * This is the function called by the router's renderRoot callback
- * instead of reactRoot.render() directly.
+ * Trigger a transition render for non-navigation updates.
+ * React keeps the old committed tree visible while any new Suspense
+ * boundaries in the update resolve.
  *
- * Falls back to no-op if TransitionRoot hasn't mounted yet (shouldn't
- * happen in practice — TransitionRoot mounts during hydration).
+ * Used for: applyRevalidation, popstate replay with cached payload.
  */
 export declare function transitionRender(element: ReactNode): void;
+/**
+ * Run a full navigation inside a React transition with optimistic pending URL.
+ *
+ * The `perform` callback runs inside `startTransition` — it should fetch the
+ * RSC payload, update router state, and return the wrapped React element.
+ * The pending URL shows immediately (useOptimistic urgent update) and reverts
+ * to null when the transition commits (atomic with the new tree).
+ *
+ * Returns a Promise that resolves when the async work completes (note: the
+ * React transition may not have committed yet, but all state updates are done).
+ *
+ * Used for: navigate(), refresh(), popstate with fetch.
+ */
+export declare function navigateTransition(pendingUrl: string, perform: () => Promise<ReactNode>): Promise<void>;
 /**
  * Check if the TransitionRoot is mounted and ready for renders.
  * Used by browser-entry.ts to guard against renders before hydration.

package/dist/client/transition-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAalE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAY7E;AAID;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}
+{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAuBf;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CA8B7E;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}

package/dist/client/use-navigation-pending.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-navigation-pending.d.ts","sourceRoot":"","sources":["../../src/client/use-navigation-pending.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAK9C"}
+{"version":3,"file":"use-navigation-pending.d.ts","sourceRoot":"","sources":["../../src/client/use-navigation-pending.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAI9C"}

package/package.json

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

package/src/client/browser-entry.ts

@@ -52,7 +52,7 @@ import { isPageUnloading } from './unload-guard.js';
 import { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 import { handleLinkClick, handleLinkHover } from './browser-links.js';
-import { TransitionRoot, transitionRender } from './transition-root.js';
+import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -289,14 +289,12 @@ function bootstrap(runtimeConfig: typeof config): void {
       setNavigationState({
         params: earlyParams as Record<string, string | string[]>,
         pathname: window.location.pathname,
-        pendingUrl: null,
       });
       delete (self as unknown as Record<string, unknown>).__timber_params;
     } else {
       setNavigationState({
         params: {},
         pathname: window.location.pathname,
-        pendingUrl: null,
       });
     }
 
@@ -370,22 +368,12 @@ function bootstrap(runtimeConfig: typeof config): void {
       },
 
       // Render decoded RSC tree via TransitionRoot's state-based mechanism.
-      // Wraps with NavigationProvider (for atomic useParams/usePathname updates)
-      // and TimberNuqsAdapter (for nuqs context).
+      // Used for non-navigation renders (popstate cached replay, applyRevalidation).
+      // Wraps with NavigationProvider + TimberNuqsAdapter.
       //
-      // The router calls setNavigationState() before renderRoot(), so
-      // getNavigationState() returns the new params/pathname. By wrapping
-      // the element in NavigationProvider here, the context value and the
-      // RSC tree are passed to startTransition(() => setState()) in the same
-      // call — making the update atomic. Preserved layout components that call
-      // useParams() or usePathname() re-render in the same pass as the
-      // new tree, preventing the dual-active-state flash.
-      //
-      // Using transitionRender instead of reactRoot.render() enables
-      // client-side Suspense deferral: React keeps the old committed tree
-      // visible while new Suspense boundaries in the navigation resolve.
-      // This is the client-side equivalent of deferSuspenseFor on the server.
-      // See design/05-streaming.md.
+      // For navigation renders (navigate, refresh, popstate-with-fetch),
+      // navigateTransition is used instead — it wraps the entire navigation
+      // in a React transition with useOptimistic for the pending URL.
       renderRoot: (element: unknown) => {
         const navState = getNavigationState();
         const withNav = createElement(NavigationProvider, { value: navState }, element as React.ReactNode);
@@ -393,6 +381,26 @@ function bootstrap(runtimeConfig: typeof config): void {
         transitionRender(wrapped);
       },
 
+      // Run a navigation inside a React transition with optimistic pending URL.
+      // The entire fetch + state update runs inside startTransition. useOptimistic
+      // shows the pending URL immediately and reverts to null when the transition
+      // commits (atomic with the new tree + params).
+      //
+      // The perform callback receives a wrapPayload function that wraps the
+      // decoded RSC payload with NavigationProvider + NuqsAdapter — this must
+      // happen inside the transition so the NavigationProvider reads the
+      // UPDATED navigation state (set by the router inside perform).
+      navigateTransition: (pendingUrl: string, perform) => {
+        return navigateTransition(pendingUrl, async () => {
+          const payload = await perform((rawPayload: unknown) => {
+            const navState = getNavigationState();
+            const withNav = createElement(NavigationProvider, { value: navState }, rawPayload as React.ReactNode);
+            return createElement(TimberNuqsAdapter, null, withNav);
+          });
+          return payload as React.ReactNode;
+        });
+      },
+
       // 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.
@@ -441,7 +449,6 @@ function bootstrap(runtimeConfig: typeof config): void {
     setNavigationState({
       params: lateTimberParams as Record<string, string | string[]>,
       pathname: window.location.pathname,
-      pendingUrl: null,
     });
     delete (self as unknown as Record<string, unknown>).__timber_params;
   }

package/src/client/link-status-provider.tsx

@@ -3,32 +3,28 @@
 // LinkStatusProvider — client component that provides per-link pending status
 // via React context. Used inside <Link> to power useLinkStatus().
 //
-// Reads pendingUrl from NavigationContext so the pending status updates
-// atomically with params/pathname in the same React commit. This prevents
-// the gap where the spinner disappears before the active state updates.
+// Reads pendingUrl from PendingNavigationContext (provided by TransitionRoot).
+// The pending URL is set as an URGENT update at navigation start (shows
+// immediately) and cleared inside startTransition when the new tree commits
+// (atomic with params/pathname). This eliminates both:
+// 1. The delay before showing the spinner (urgent update, not deferred)
+// 2. The gap between spinner disappearing and active state updating (same commit)
 
 import type { ReactNode } from 'react';
 import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
-import { useNavigationContext } from './navigation-context.js';
+import { usePendingNavigationUrl } from './pending-navigation-context.js';
 
 const NOT_PENDING: LinkStatus = { pending: false };
 const IS_PENDING: LinkStatus = { pending: true };
 
 /**
- * Client component that reads the pending URL from NavigationContext and
- * provides a scoped LinkStatusContext to children. Renders no extra DOM —
+ * Client component that reads the pending URL from PendingNavigationContext
+ * and provides a scoped LinkStatusContext to children. Renders no extra DOM —
  * just a context provider around children.
- *
- * Because pendingUrl lives in NavigationContext alongside params and pathname,
- * all three update in the same React commit via renderRoot(). This eliminates
- * the two-commit timing gap that existed when pendingUrl was read via
- * useSyncExternalStore (external module-level state) while params came from
- * NavigationContext (React context).
  */
 export function LinkStatusProvider({ href, children }: { href: string; children: ReactNode }) {
-  const navState = useNavigationContext();
-  // During SSR or outside NavigationProvider, never pending
-  const status = navState?.pendingUrl === href ? IS_PENDING : NOT_PENDING;
+  const pendingUrl = usePendingNavigationUrl();
+  const status = pendingUrl === href ? IS_PENDING : NOT_PENDING;
 
   return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
 }

package/src/client/navigation-context.ts

@@ -35,14 +35,6 @@ import React, { createElement, type ReactNode } from 'react';
 export interface NavigationState {
   params: Record<string, string | string[]>;
   pathname: string;
-  /**
-   * The URL currently being navigated to, or null if idle.
-   * Used by LinkStatusProvider to determine pending status atomically
-   * with params/pathname — all three update in the same React commit
-   * via NavigationProvider, preventing the gap where the spinner
-   * disappears before the active state updates.
-   */
-  pendingUrl: string | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -115,7 +107,7 @@ export function NavigationProvider({ value, children }: NavigationProviderProps)
  * This exists only as a communication channel between the router
  * (which knows the new nav state) and renderRoot (which wraps the element).
  */
-let _currentNavState: NavigationState = { params: {}, pathname: '/', pendingUrl: null };
+let _currentNavState: NavigationState = { params: {}, pathname: '/' };
 
 export function setNavigationState(state: NavigationState): void {
   _currentNavState = state;

package/src/client/pending-navigation-context.ts

@@ -0,0 +1,66 @@
+/**
+ * PendingNavigationContext — React context for the in-flight navigation URL.
+ *
+ * Provided by TransitionRoot. The value is the URL being navigated to,
+ * or null when idle. Used by:
+ * - LinkStatusProvider to show per-link pending spinners
+ * - useNavigationPending to return a global pending boolean
+ *
+ * The pending URL is set as an URGENT update (shows immediately) and
+ * cleared inside startTransition (commits atomically with the new tree).
+ * This ensures pending state appears instantly on navigation start and
+ * disappears in the same React commit as the new params/tree.
+ *
+ * Separate from NavigationContext (which holds params + pathname) because
+ * the pending URL is managed as React state in TransitionRoot, while
+ * params/pathname are set via module-level state read by renderRoot.
+ * Both contexts commit together in the same transition.
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import React, { createElement, type ReactNode } from 'react';
+
+// ---------------------------------------------------------------------------
+// Lazy context initialization (same pattern as NavigationContext)
+// ---------------------------------------------------------------------------
+
+let _context: React.Context<string | null> | undefined;
+
+function getOrCreateContext(): React.Context<string | null> | undefined {
+  if (_context !== undefined) return _context;
+  if (typeof React.createContext === 'function') {
+    _context = React.createContext<string | null>(null);
+  }
+  return _context;
+}
+
+/**
+ * Read the pending navigation URL from context.
+ * Returns null during SSR (no provider) or in the RSC environment.
+ * Internal — used by LinkStatusProvider and useNavigationPending.
+ */
+export function usePendingNavigationUrl(): string | null {
+  const ctx = getOrCreateContext();
+  if (!ctx) return null;
+  if (typeof React.useContext !== 'function') return null;
+  return React.useContext(ctx);
+}
+
+// ---------------------------------------------------------------------------
+// Provider component
+// ---------------------------------------------------------------------------
+
+export function PendingNavigationProvider({
+  value,
+  children,
+}: {
+  value: string | null;
+  children?: ReactNode;
+}): React.ReactElement {
+  const ctx = getOrCreateContext();
+  if (!ctx) {
+    return children as React.ReactElement;
+  }
+  return createElement(ctx.Provider, { value }, children);
+}