@timber-js/app 0.2.0-alpha.54 → 0.2.0-alpha.55

package/LICENSE

@@ -0,0 +1,8 @@
+DONTFUCKINGUSE LICENSE
+
+Copyright (c) 2025 Daniel Saewitz
+
+This software may not be used, copied, modified, merged, published,
+distributed, sublicensed, or sold by anyone other than the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/dist/client/index.js

@@ -4,7 +4,7 @@ import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-que
 import { n as useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-Bmugn-ao.js";
 import { a as _setCachedSearch, c as cachedSearch, d as globalRouter, i as setSsrData, l as cachedSearchParams, n as clearSsrData, o as _setCurrentParams, r as getSsrData, s as _setGlobalRouter, t as TimberErrorBoundary, u as currentParams } from "../_chunks/error-boundary-B9vT_YK_.js";
 import { t as _registerUseCookieModule } from "../_chunks/define-cookie-k9btcEfI.js";
-import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useSyncExternalStore, useTransition } from "react";
+import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useEffect, useRef, useState, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
 /**
@@ -41,165 +41,6 @@ function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
 //#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 LinkStatusProvider (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 LinkStatusProvider
-* and useNavigationPending.
-*
-* 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/link-status-provider.tsx
-var NOT_PENDING = { pending: false };
-var IS_PENDING = { pending: true };
-/**
-* 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.
-*/
-function LinkStatusProvider({ href, children }) {
-	const status = usePendingNavigationUrl() === href ? IS_PENDING : NOT_PENDING;
-	return /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
-		value: status,
-		children
-	});
-}
-//#endregion
 //#region src/client/router-ref.ts
 /**
 * Set the global router instance. Called once during bootstrap.
@@ -224,6 +65,48 @@ function getRouterOrNull() {
 	return globalRouter;
 }
 //#endregion
+//#region src/client/link-pending-store.ts
+var LINK_PENDING_KEY = Symbol.for("__timber_link_pending");
+/** Status object indicating link is pending — shared reference */
+var PENDING_LINK_STATUS = { pending: true };
+/** Status object indicating link is idle — shared reference */
+var IDLE_LINK_STATUS = { pending: false };
+function getStore() {
+	const g = globalThis;
+	if (!g[LINK_PENDING_KEY]) g[LINK_PENDING_KEY] = {
+		current: null,
+		navId: 0
+	};
+	return g[LINK_PENDING_KEY];
+}
+/**
+* Register the link instance that initiated the current navigation.
+*
+* Called from <Link>'s click handler before router.navigate().
+* - Resets the previous pending link to IDLE (urgent update, immediate)
+* - Does NOT set the new link to PENDING here — the Link's click handler
+*   calls setLinkStatus(PENDING) directly for the eager show
+* - Increments the navId counter for stale-clear protection
+*
+* Pass `null` to clear (e.g., for programmatic navigations).
+*/
+function setLinkForCurrentNavigation(link) {
+	const store = getStore();
+	const prev = store.current;
+	if (prev && prev !== link) prev.setLinkStatus(IDLE_LINK_STATUS);
+	store.current = link;
+	store.navId++;
+}
+/**
+* Unmount a link instance from navigation tracking. Called when a Link
+* component unmounts while it is the current navigation link. Prevents
+* calling setState on an unmounted component.
+*/
+function unmountLinkForCurrentNavigation(link) {
+	const store = getStore();
+	if (store.current === link) store.current = null;
+}
+//#endregion
 //#region src/client/link.tsx
 /**
 * Read the current URL's search string without requiring a React hook.
@@ -346,6 +229,16 @@ function Link({ href, prefetch, scroll, segmentParams, searchParams, preserveSea
 		params: segmentParams,
 		searchParams
 	});
+	const [linkStatus, setLinkStatus] = useState(IDLE_LINK_STATUS);
+	const linkInstanceRef = useRef(null);
+	if (!linkInstanceRef.current) linkInstanceRef.current = { setLinkStatus };
+	else linkInstanceRef.current.setLinkStatus = setLinkStatus;
+	useEffect(() => {
+		const instance = linkInstanceRef.current;
+		return () => {
+			if (instance) unmountLinkForCurrentNavigation(instance);
+		};
+	}, []);
 	const resolvedHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : baseHref;
 	const internal = isInternalHref(resolvedHref);
 	const handleClick = internal ? (event) => {
@@ -366,6 +259,8 @@ function Link({ href, prefetch, scroll, segmentParams, searchParams, preserveSea
 		event.preventDefault();
 		const shouldScroll = scroll !== false;
 		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
+		setLinkStatus(PENDING_LINK_STATUS);
+		setLinkForCurrentNavigation(linkInstanceRef.current);
 		router.navigate(navHref, { scroll: shouldScroll });
 	} : userOnClick;
 	const handleMouseEnter = internal && prefetch ? (event) => {
@@ -381,8 +276,8 @@ function Link({ href, prefetch, scroll, segmentParams, searchParams, preserveSea
 		href: resolvedHref,
 		onClick: handleClick,
 		onMouseEnter: handleMouseEnter,
-		children: /* @__PURE__ */ jsx(LinkStatusProvider, {
-			href: resolvedHref,
+		children: /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
+			value: linkStatus,
 			children
 		})
 	});
@@ -519,6 +414,150 @@ 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.