@timber-js/app 0.2.0-alpha.68 → 0.2.0-alpha.69

package/dist/client/index.js

@@ -114,6 +114,211 @@ function unmountLinkForCurrentNavigation(link) {
 */
 function setNavLinkMetadata(metadata) {}
 //#endregion
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current route params and pathname, updated atomically
+* with the RSC tree on each navigation. This replaces the previous
+* useSyncExternalStore approach for useSegmentParams() and usePathname(),
+* which suffered from a timing gap: the new tree could commit before
+* the external store re-renders fired, causing a frame where both
+* old and new active states were visible simultaneously.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (useParams, usePathname) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+* Symbol.for keys. The RSC client bundler can duplicate this module
+* across chunks (browser-entry graph + client-reference graph). With
+* ESM output, each chunk gets its own module scope — module-level
+* variables would create separate singleton instances per chunk.
+* globalThis guarantees a single instance regardless of duplication.
+*
+* This workaround will be removed when Rolldown ships `format: 'app'`
+* (module registry format that deduplicates like webpack/Turbopack).
+* See design/27-chunking-strategy.md.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*
+* Context instances are stored on globalThis (NOT in module-level
+* variables) because the ESM bundler can duplicate this module across
+* chunks. Module-level variables would create separate instances per
+* chunk — the provider in NavigationRoot (index chunk) would use
+* context A while the consumer in useNavigationPending (shared chunk)
+* reads from context B. globalThis guarantees a single instance.
+*
+* See design/27-chunking-strategy.md §"Singleton Safety"
+*/
+var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
+var PENDING_CTX_KEY = Symbol.for("__timber_pending_nav_ctx");
+function getOrCreateContext() {
+	const existing = globalThis[NAV_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[NAV_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by useSegmentParams() and usePathname().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Navigation state communicated between the router and renderRoot.
+*
+* The router calls setNavigationState() before renderRoot(). The
+* renderRoot callback reads via getNavigationState() to create the
+* NavigationProvider with the correct params/pathname.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+*
+* Stored on globalThis (like the context instances above) because the
+* router lives in one chunk while renderRoot lives in another. Module-
+* level variables would be separate per chunk.
+*/
+var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
+function _getNavStateStore() {
+	const g = globalThis;
+	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
+		params: {},
+		pathname: "/"
+	} };
+	return g[NAV_STATE_KEY];
+}
+function setNavigationState(state) {
+	_getNavStateStore().current = state;
+}
+function getNavigationState() {
+	return _getNavStateStore().current;
+}
+/**
+* Separate context for the in-flight navigation URL. Provided by
+* NavigationRoot (urgent useState), consumed by useNavigationPending
+* and TopLoader. Per-link pending state uses useOptimistic instead
+* (see link-pending-store.ts).
+*
+* Uses globalThis via Symbol.for for the same reason as NavigationContext
+* above — the bundler may duplicate this module across chunks, and module-
+* level variables would create separate context instances.
+*/
+function getOrCreatePendingContext() {
+	const existing = globalThis[PENDING_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[PENDING_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the pending navigation URL from context.
+* Returns null during SSR (no provider) or in the RSC environment.
+*/
+function usePendingNavigationUrl() {
+	const ctx = getOrCreatePendingContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+//#endregion
+//#region src/client/top-loader.tsx
+/**
+* TopLoader — Built-in progress bar for client navigations.
+*
+* Shows an animated progress bar at the top of the viewport while an RSC
+* navigation is in flight. Injected automatically by the framework into
+* NavigationRoot — users never render this component directly.
+*
+* Configuration is via timber.config.ts `topLoader` key. Enabled by default.
+* Users who want a fully custom progress indicator disable the built-in one
+* (`topLoader: { enabled: false }`) and use `useNavigationPending()` directly.
+*
+* Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
+* width over ~30s using ease-out timing. When navigation completes, the bar
+* snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).
+*
+* Phase transitions are derived synchronously during render (React's
+* getDerivedStateFromProps pattern) — no useEffect needed for state tracking.
+* The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.
+*
+* When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar
+* stays invisible during the delay period. If navigation finishes before the
+* delay, the bar was never visible so the finish transition is also invisible.
+*
+* See design/19-client-navigation.md §"useNavigationPending()"
+* See LOCAL-336 for design decisions.
+*/
+//#endregion
+//#region src/client/navigation-root.tsx
+/**
+* Module-level flag indicating a hard (MPA) navigation is in progress.
+*
+* When true:
+* - NavigationRoot throws an unresolved thenable to suspend forever,
+*   preventing React from rendering children during page teardown
+*   (avoids "Rendered more hooks" crashes).
+* - The Navigation API handler skips interception, letting the browser
+*   perform a full page load (prevents infinite loops where
+*   window.location.href → navigate event → router.navigate → 500 →
+*   window.location.href → ...).
+*
+* Uses globalThis for singleton guarantee across chunks (same pattern
+* as NavigationContext). See design/19-client-navigation.md §"Singleton
+* Guarantee via globalThis".
+*/
+var HARD_NAV_KEY = Symbol.for("__timber_hard_navigating");
+function getHardNavStore() {
+	const g = globalThis;
+	if (!g[HARD_NAV_KEY]) g[HARD_NAV_KEY] = { value: false };
+	return g[HARD_NAV_KEY];
+}
+/**
+* Set the hard-navigating flag. Call this BEFORE setting
+* window.location.href or window.location.reload() to prevent:
+* 1. React from rendering children during page teardown
+* 2. Navigation API from intercepting the hard navigation
+*/
+function setHardNavigating(value) {
+	getHardNavStore().value = value;
+}
+//#endregion
 //#region src/client/navigation-api.ts
 /**
 * Returns true if the Navigation API is available in the current environment.
@@ -485,150 +690,6 @@ var HistoryStack = class {
 	}
 };
 //#endregion
-//#region src/client/navigation-context.ts
-/**
-* NavigationContext — React context for navigation state.
-*
-* Holds the current route params and pathname, updated atomically
-* with the RSC tree on each navigation. This replaces the previous
-* useSyncExternalStore approach for useSegmentParams() and usePathname(),
-* which suffered from a timing gap: the new tree could commit before
-* the external store re-renders fired, causing a frame where both
-* old and new active states were visible simultaneously.
-*
-* By wrapping the RSC payload element in NavigationProvider inside
-* renderRoot(), the context value and the element tree are passed to
-* reactRoot.render() in the same call — atomic by construction.
-* All consumers (useParams, usePathname) see the new values in the
-* same render pass as the new tree.
-*
-* During SSR, no NavigationProvider is mounted. Hooks fall back to
-* the ALS-backed getSsrData() for per-request isolation.
-*
-* IMPORTANT: createContext and useContext are NOT available in the RSC
-* environment (React Server Components use a stripped-down React).
-* The context is lazily initialized on first access, and all functions
-* that depend on these APIs are safe to call from any environment —
-* they return null or no-op when the APIs aren't available.
-*
-* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
-* Symbol.for keys. The RSC client bundler can duplicate this module
-* across chunks (browser-entry graph + client-reference graph). With
-* ESM output, each chunk gets its own module scope — module-level
-* variables would create separate singleton instances per chunk.
-* globalThis guarantees a single instance regardless of duplication.
-*
-* This workaround will be removed when Rolldown ships `format: 'app'`
-* (module registry format that deduplicates like webpack/Turbopack).
-* See design/27-chunking-strategy.md.
-*
-* See design/19-client-navigation.md §"NavigationContext"
-*/
-/**
-* The context is created lazily to avoid calling createContext at module
-* level. In the RSC environment, React.createContext doesn't exist —
-* calling it at import time would crash the server.
-*
-* Context instances are stored on globalThis (NOT in module-level
-* variables) because the ESM bundler can duplicate this module across
-* chunks. Module-level variables would create separate instances per
-* chunk — the provider in TransitionRoot (index chunk) would use
-* context A while the consumer in useNavigationPending (shared chunk)
-* reads from context B. globalThis guarantees a single instance.
-*
-* See design/27-chunking-strategy.md §"Singleton Safety"
-*/
-var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
-var PENDING_CTX_KEY = Symbol.for("__timber_pending_nav_ctx");
-function getOrCreateContext() {
-	const existing = globalThis[NAV_CTX_KEY];
-	if (existing !== void 0) return existing;
-	if (typeof React.createContext === "function") {
-		const ctx = React.createContext(null);
-		globalThis[NAV_CTX_KEY] = ctx;
-		return ctx;
-	}
-}
-/**
-* Read the navigation context. Returns null during SSR (no provider)
-* or in the RSC environment (no context available).
-* Internal — used by useSegmentParams() and usePathname().
-*/
-function useNavigationContext() {
-	const ctx = getOrCreateContext();
-	if (!ctx) return null;
-	if (typeof React.useContext !== "function") return null;
-	return React.useContext(ctx);
-}
-/**
-* Wraps children with NavigationContext.Provider.
-*
-* Used in browser-entry.ts renderRoot to wrap the RSC payload element
-* so that navigation state updates atomically with the tree render.
-*/
-function NavigationProvider({ value, children }) {
-	const ctx = getOrCreateContext();
-	if (!ctx) return children;
-	return createElement(ctx.Provider, { value }, children);
-}
-/**
-* Navigation state communicated between the router and renderRoot.
-*
-* The router calls setNavigationState() before renderRoot(). The
-* renderRoot callback reads via getNavigationState() to create the
-* NavigationProvider with the correct params/pathname.
-*
-* This is NOT used by hooks directly — hooks read from React context.
-*
-* Stored on globalThis (like the context instances above) because the
-* router lives in one chunk while renderRoot lives in another. Module-
-* level variables would be separate per chunk.
-*/
-var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
-function _getNavStateStore() {
-	const g = globalThis;
-	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
-		params: {},
-		pathname: "/"
-	} };
-	return g[NAV_STATE_KEY];
-}
-function setNavigationState(state) {
-	_getNavStateStore().current = state;
-}
-function getNavigationState() {
-	return _getNavStateStore().current;
-}
-/**
-* Separate context for the in-flight navigation URL. Provided by
-* TransitionRoot (urgent useState), consumed by useNavigationPending
-* and TopLoader. Per-link pending state uses useOptimistic instead
-* (see link-pending-store.ts).
-*
-* Uses globalThis via Symbol.for for the same reason as NavigationContext
-* above — the bundler may duplicate this module across chunks, and module-
-* level variables would create separate context instances.
-*/
-function getOrCreatePendingContext() {
-	const existing = globalThis[PENDING_CTX_KEY];
-	if (existing !== void 0) return existing;
-	if (typeof React.createContext === "function") {
-		const ctx = React.createContext(null);
-		globalThis[PENDING_CTX_KEY] = ctx;
-		return ctx;
-	}
-}
-/**
-* Read the pending navigation URL from context.
-* Returns null during SSR (no provider) or in the RSC environment.
-*/
-function usePendingNavigationUrl() {
-	const ctx = getOrCreatePendingContext();
-	if (!ctx) return null;
-	if (typeof React.useContext !== "function") return null;
-	return React.useContext(ctx);
-}
-//#endregion
 //#region src/client/use-params.ts
 /**
 * Set the current route params in the module-level store.
@@ -1269,6 +1330,7 @@ function createRouter(deps) {
 			restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
 		} catch (error) {
 			if (error instanceof VersionSkewError) {
+				setHardNavigating(true);
 				const { triggerStaleReload } = await import("../_chunks/stale-reload-BeyHXZ5B.js");
 				triggerStaleReload();
 				return new Promise(() => {});
@@ -1280,12 +1342,14 @@ function createRouter(deps) {
 				return;
 			}
 			if (error instanceof ServerErrorResponse) {
+				setHardNavigating(true);
 				window.location.href = error.url;
 				return new Promise(() => {});
 			}
 			if (isAbortError(error)) return;
 			throw error;
 		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
 			setPending(false);
 			deps.completeRouterNavigation?.();
 		}
@@ -1304,7 +1368,11 @@ function createRouter(deps) {
 					navState
 				};
 			}));
+		} catch (error) {
+			if (isAbortError(error)) return;
+			throw error;
 		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
 			setPending(false);
 			deps.completeRouterNavigation?.();
 		}
@@ -1330,7 +1398,11 @@ function createRouter(deps) {
 					};
 				}));
 				restoreScrollAfterPaint(scrollY);
+			} catch (error) {
+				if (isAbortError(error)) return;
+				throw error;
 			} finally {
+				if (currentNavAbort === navAbort) currentNavAbort = null;
 				setPending(false);
 			}
 		}