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

package/dist/_chunks/{navigation-root-CeNTCxzS.js → navigation-root-B5-RmsPi.js}

@@ -1,33 +1,40 @@
-import "./use-segment-params-ByGqwUuO.js";
-import "react";
-//#region src/client/link-pending-store.ts
-var LINK_PENDING_KEY = Symbol.for("__timber_link_pending");
-/** Status object: link idle */
-var LINK_IDLE = { isPending: false };
-function getStore() {
-	const g = globalThis;
-	if (!g[LINK_PENDING_KEY]) g[LINK_PENDING_KEY] = { current: null };
-	return g[LINK_PENDING_KEY];
+import "./use-segment-params-CIeinIx2.js";
+import { n as getRouterOrNull } from "./router-ref-B2-2kIIC.js";
+import { useSyncExternalStore } from "react";
+//#region src/client/use-pending-navigation.ts
+function subscribe(onStoreChange) {
+	const router = getRouterOrNull();
+	if (!router) return () => {};
+	return router.onPendingChange(onStoreChange);
 }
-/**
-* Register the link instance that initiated the current navigation.
-* Called from Link's click handler. Does NOT call setIsPending —
-* that happens via activateLinkPending() called from NavigationRoot.
-*
-* Resets the previous link to idle immediately if a different link
-* is being registered (handles overlapping link clicks).
-*/
-function setLinkForCurrentNavigation(link) {
-	const store = getStore();
-	if (store.current && store.current !== link) store.current.setIsPending(LINK_IDLE);
-	store.current = link;
+function getSnapshot() {
+	const router = getRouterOrNull();
+	return router ? router.isPending() : false;
 }
+var getServerSnapshot = getSnapshot;
 /**
-* Unmount a link instance from navigation tracking.
+* Returns true while an RSC navigation is in flight.
+*
+* Reads from the router's external pending store via useSyncExternalStore.
+* Only components that call this hook re-render when pending state
+* changes — no full-tree re-render.
+*
+* ```tsx
+* 'use client'
+* import { usePendingNavigation } from '@timber-js/app/client'
+*
+* export function NavBar() {
+*   const isPending = usePendingNavigation()
+*   return (
+*     <nav className={isPending ? 'opacity-50' : ''}>
+*       <Link href="/dashboard">Dashboard</Link>
+*     </nav>
+*   )
+* }
+* ```
 */
-function unmountLinkForCurrentNavigation(link) {
-	const store = getStore();
-	if (store.current === link) store.current = null;
+function usePendingNavigation() {
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 //#endregion
 //#region src/client/top-loader.tsx
@@ -91,6 +98,6 @@ function setHardNavigating(value) {
 	getHardNavStore().value = value;
 }
 //#endregion
-export { unmountLinkForCurrentNavigation as i, LINK_IDLE as n, setLinkForCurrentNavigation as r, setHardNavigating as t };
+export { usePendingNavigation as n, setHardNavigating as t };
 
-//# sourceMappingURL=navigation-root-CeNTCxzS.js.map
+//# sourceMappingURL=navigation-root-B5-RmsPi.js.map

package/dist/_chunks/navigation-root-B5-RmsPi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-root-B5-RmsPi.js","names":[],"sources":["../../src/client/use-pending-navigation.ts","../../src/client/top-loader.tsx","../../src/client/navigation-root.tsx"],"sourcesContent":["import { useSyncExternalStore } from 'react';\nimport { getRouterOrNull } from './router-ref.js';\n\nfunction subscribe(onStoreChange: () => void): () => void {\n  const router = getRouterOrNull();\n  if (!router) return () => {};\n  return router.onPendingChange(onStoreChange);\n}\n\nfunction getSnapshot(): boolean {\n  const router = getRouterOrNull();\n  return router ? router.isPending() : false;\n}\n\nconst getServerSnapshot = getSnapshot;\n\n/**\n * Returns true while an RSC navigation is in flight.\n *\n * Reads from the router's external pending store via useSyncExternalStore.\n * Only components that call this hook re-render when pending state\n * changes — no full-tree re-render.\n *\n * ```tsx\n * 'use client'\n * import { usePendingNavigation } from '@timber-js/app/client'\n *\n * export function NavBar() {\n *   const isPending = usePendingNavigation()\n *   return (\n *     <nav className={isPending ? 'opacity-50' : ''}>\n *       <Link href=\"/dashboard\">Dashboard</Link>\n *     </nav>\n *   )\n * }\n * ```\n */\nexport function usePendingNavigation(): boolean {\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n","/**\n * TopLoader — Built-in progress bar for client navigations.\n *\n * Shows an animated progress bar at the top of the viewport while an RSC\n * navigation is in flight. Injected automatically by the framework into\n * NavigationRoot — users never render this component directly.\n *\n * Configuration is via timber.config.ts `topLoader` key. Enabled by default.\n * Users who want a fully custom progress indicator disable the built-in one\n * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.\n *\n * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%\n * width over ~30s using ease-out timing. When navigation completes, the bar\n * snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).\n *\n * Phase transitions are derived synchronously during render (React's\n * getDerivedStateFromProps pattern) — no useEffect needed for state tracking.\n * The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.\n *\n * When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar\n * stays invisible during the delay period. If navigation finishes before the\n * delay, the bar was never visible so the finish transition is also invisible.\n *\n * See design/19-client-navigation.md §\"usePendingNavigation()\"\n * See LOCAL-336 for design decisions.\n */\n\n'use client';\n\nimport { useState, createElement } from 'react';\nimport { usePendingNavigation } from './use-pending-navigation.js';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface TopLoaderConfig {\n  /** Whether the top-loader is enabled. Default: true. */\n  enabled?: boolean;\n  /** Bar color. Default: '#2299DD'. */\n  color?: string;\n  /** Bar height in pixels. Default: 3. */\n  height?: number;\n  /** Show subtle glow/shadow effect. Default: false. */\n  shadow?: boolean;\n  /** Delay in ms before showing the bar. Default: 0. */\n  delay?: number;\n  /** CSS z-index. Default: 1600. */\n  zIndex?: number;\n}\n\n// ─── Defaults ────────────────────────────────────────────────────\n\nconst DEFAULT_COLOR = '#2299DD';\nconst DEFAULT_HEIGHT = 3;\nconst DEFAULT_SHADOW = false;\nconst DEFAULT_DELAY = 0;\nconst DEFAULT_Z_INDEX = 1600;\n\n// ─── Keyframes ───────────────────────────────────────────────────\n\n// Unique keyframes name to avoid collisions with user styles.\nconst CRAWL_KEYFRAMES = '__timber_top_loader_crawl';\nconst APPEAR_KEYFRAMES = '__timber_top_loader_appear';\nconst FINISH_KEYFRAMES = '__timber_top_loader_finish';\n\n// Track whether the @keyframes rules have been injected into the document.\nlet keyframesInjected = false;\n\n/**\n * Inject the @keyframes rules into the document head once.\n * Called during render (idempotent). Uses a <style> tag so the\n * animations are available for inline-styled elements.\n */\nfunction ensureKeyframes(): void {\n  if (keyframesInjected) return;\n  if (typeof document === 'undefined') return;\n\n  const style = document.createElement('style');\n  style.textContent = `\n@keyframes ${CRAWL_KEYFRAMES} {\n  0% { width: 0%; }\n  100% { width: 90%; }\n}\n@keyframes ${APPEAR_KEYFRAMES} {\n  from { opacity: 0; }\n  to { opacity: 1; }\n}\n@keyframes ${FINISH_KEYFRAMES} {\n  0% { width: 90%; opacity: 1; }\n  50% { width: 100%; opacity: 1; }\n  100% { width: 100%; opacity: 0; }\n}\n`;\n  document.head.appendChild(style);\n  keyframesInjected = true;\n}\n\n// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Internal top-loader component. Injected by NavigationRoot.\n *\n * Reads pending navigation state from PendingNavigationContext.\n * Phase transitions are derived synchronously during render:\n *\n *   hidden → crawling:   when isPending becomes true\n *   crawling → finishing: when isPending becomes false\n *   finishing → hidden:   when CSS transition ends (onTransitionEnd)\n *   finishing → crawling: when isPending becomes true again\n *\n * No useEffect — all state changes are either derived during render\n * (getDerivedStateFromProps pattern) or triggered by DOM events.\n */\nexport function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {\n  // Read pending state from the router's external store via\n  // useSyncExternalStore (inside usePendingNavigation). Only this\n  // component re-renders when pending changes — no full-tree re-render.\n  const isPending = usePendingNavigation();\n\n  const color = config?.color ?? DEFAULT_COLOR;\n  const height = config?.height ?? DEFAULT_HEIGHT;\n  const shadow = config?.shadow ?? DEFAULT_SHADOW;\n  const delay = config?.delay ?? DEFAULT_DELAY;\n  const zIndex = config?.zIndex ?? DEFAULT_Z_INDEX;\n\n  const [phase, setPhase] = useState<'hidden' | 'crawling' | 'finishing'>('hidden');\n\n  // ─── Synchronous phase derivation (getDerivedStateFromProps) ──\n  // React allows setState during render if the value changes — it\n  // immediately re-renders with the updated state before committing.\n\n  if (isPending && (phase === 'hidden' || phase === 'finishing')) {\n    setPhase('crawling');\n  }\n  if (!isPending && phase === 'crawling') {\n    setPhase('finishing');\n  }\n\n  // Inject keyframes on first visible render (idempotent)\n  if (phase !== 'hidden') {\n    ensureKeyframes();\n  }\n\n  if (phase === 'hidden') return null;\n\n  // ─── Styles ──────────────────────────────────────────────────\n\n  const containerStyle: React.CSSProperties = {\n    position: 'fixed',\n    top: 0,\n    left: 0,\n    width: '100%',\n    height: `${height}px`,\n    zIndex,\n    pointerEvents: 'none',\n  };\n\n  const barStyle: React.CSSProperties = {\n    height: '100%',\n    backgroundColor: color,\n    ...(phase === 'crawling'\n      ? {\n          // Crawl from 0% to 90% over 30s. When delay > 0, both the crawl\n          // and a visibility animation are delayed — the bar stays at width 0%\n          // and opacity 0 during the delay, then appears and starts crawling.\n          // With delay 0, the appear animation is instant (0s duration, no delay).\n          animation: [\n            `${CRAWL_KEYFRAMES} 30s ease-out ${delay}ms forwards`,\n            `${APPEAR_KEYFRAMES} 0s ${delay}ms both`,\n          ].join(', '),\n        }\n      : {\n          // Finishing: fill to 100% then fade out via a keyframe animation.\n          // We use a keyframe instead of a CSS transition because the\n          // animation-to-transition handoff is unreliable — the browser\n          // may not capture the animated width as the transition's \"from\"\n          // value when both the animation removal and transition are\n          // applied in the same render frame.\n          animation: `${FINISH_KEYFRAMES} 400ms ease forwards`,\n        }),\n    ...(shadow\n      ? {\n          boxShadow: `0 0 10px ${color}, 0 0 5px ${color}`,\n        }\n      : {}),\n  };\n\n  // Clean up the finishing phase when the finish animation completes.\n  const handleAnimationEnd =\n    phase === 'finishing'\n      ? (e: React.AnimationEvent) => {\n          if (e.animationName === FINISH_KEYFRAMES) {\n            setPhase('hidden');\n          }\n        }\n      : undefined;\n\n  return createElement(\n    'div',\n    {\n      'style': containerStyle,\n      'aria-hidden': 'true',\n      'data-timber-top-loader': '',\n    },\n    createElement('div', { style: barStyle, onAnimationEnd: handleAnimationEnd })\n  );\n}\n","/**\n * NavigationRoot — Wrapper component for transition-based rendering.\n *\n * Solves the \"new boundary has no old content\" problem for client-side\n * navigation. When React renders a completely new Suspense boundary via\n * root.render(), it shows the fallback immediately — root.render() is\n * always an urgent update regardless of startTransition.\n *\n * NavigationRoot holds the current element in React state. Navigation\n * updates call startTransition(() => setState(newElement)), which IS\n * a transition update. React keeps the old committed tree visible while\n * any new Suspense boundaries in the transition resolve.\n *\n * Also manages `pendingUrl` as React state with an urgent/transition split:\n * - Navigation START: `setPendingUrl(url)` is an urgent update — React\n *   commits it before the next paint, showing the spinner immediately.\n * - Navigation END: `setPendingUrl(null)` is inside `startTransition`\n *   alongside `setElement(newTree)` — both commit atomically, so the\n *   spinner disappears in the same frame as the new content appears.\n *\n * Hard navigation guard: When a hard navigation is triggered (500 error,\n * version skew), the component throws an unresolved thenable AFTER all\n * hooks to suspend forever — preventing React from rendering children\n * during page teardown. The throw must come after hooks to satisfy\n * React's rules (same hook count every render) while still preventing\n * child renders that could hit hook count mismatches in components\n * whose positions shift during teardown. This pattern is borrowed from\n * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).\n *\n * See design/05-streaming.md §\"deferSuspenseFor\"\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport { createElement, Fragment, startTransition, useState, type ReactNode } from 'react';\nimport { PendingNavigationProvider } from './navigation-context.js';\nimport { TopLoader, type TopLoaderConfig } from './top-loader.js';\n\n// ─── Navigation Transition Counter ──────────────────────────────\n// Monotonically increasing counter that increments each time\n// navigateTransition() is called. Used to detect stale transitions:\n// if a newer transition started while the current one's perform()\n// was in flight, the current transition is stale and should reject.\n//\n// Separate from the link-pending navId (which only increments on\n// link clicks). This counter covers all navigation types: link clicks,\n// programmatic navigate(), refresh(), and handlePopState().\n//\n// Uses globalThis for singleton guarantee across chunks — same pattern\n// as NavigationContext and the link pending store.\n\nconst NAV_TRANSITION_KEY = Symbol.for('__timber_nav_transition_counter');\n\nfunction getTransitionCounter(): { id: number } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_TRANSITION_KEY]) {\n    g[NAV_TRANSITION_KEY] = { id: 0 };\n  }\n  return g[NAV_TRANSITION_KEY] as { id: number };\n}\n\n// ─── Hard Navigation Guard ──────────────────────────────────────\n\n/**\n * Module-level flag indicating a hard (MPA) navigation is in progress.\n *\n * When true:\n * - NavigationRoot throws an unresolved thenable to suspend forever,\n *   preventing React from rendering children during page teardown\n *   (avoids \"Rendered more hooks\" crashes).\n * - The Navigation API handler skips interception, letting the browser\n *   perform a full page load (prevents infinite loops where\n *   window.location.href → navigate event → router.navigate → 500 →\n *   window.location.href → ...).\n *\n * Uses globalThis for singleton guarantee across chunks (same pattern\n * as NavigationContext). See design/19-client-navigation.md §\"Singleton\n * Guarantee via globalThis\".\n */\nconst HARD_NAV_KEY = Symbol.for('__timber_hard_navigating');\n\nfunction getHardNavStore(): { value: boolean } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[HARD_NAV_KEY]) {\n    g[HARD_NAV_KEY] = { value: false };\n  }\n  return g[HARD_NAV_KEY] as { value: boolean };\n}\n\n/**\n * Set the hard-navigating flag. Call this BEFORE setting\n * window.location.href or window.location.reload() to prevent:\n * 1. React from rendering children during page teardown\n * 2. Navigation API from intercepting the hard navigation\n */\nexport function setHardNavigating(value: boolean): void {\n  getHardNavStore().value = value;\n}\n\n/**\n * Check if a hard navigation is in progress.\n * Used by NavigationRoot (throw unresolvedThenable) and by the\n * Navigation API handler (skip interception).\n */\nexport function isHardNavigating(): boolean {\n  return getHardNavStore().value;\n}\n\n/**\n * A thenable that never resolves. When thrown during React render,\n * it causes the component to suspend forever — React keeps the\n * old committed tree visible and never attempts to render children.\n *\n * This is the same pattern Next.js uses in app-router.tsx for MPA\n * navigations (pushRef.mpaNavigation → throw unresolvedThenable).\n */\n// for React's Suspense mechanism. Same pattern as Next.js's unresolvedThenable.\n// eslint-disable-next-line unicorn/no-thenable -- Intentionally a never-resolving thenable\nconst unresolvedThenable = { then() {} } as PromiseLike<never>;\n\n// ─── Module-level functions ──────────────────────────────────────\n\n/**\n * Module-level reference to the state setter wrapped in startTransition.\n * Used for non-navigation renders (applyRevalidation, popstate replay).\n */\nlet _transitionRender: ((element: ReactNode) => void) | null = null;\n\n/**\n * Module-level reference to the navigation transition function.\n * Wraps a full navigation (fetch + render) in a single startTransition\n * with the pending URL.\n */\nlet _navigateTransition:\n  | ((\n      pendingUrl: string,\n      perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>\n    ) => Promise<void>)\n  | null = null;\n\n// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Root wrapper component that enables transition-based rendering.\n *\n * Renders PendingNavigationProvider around children for the pending URL\n * context. The DOM tree matches the server-rendered HTML during hydration\n * (the provider renders no extra DOM elements).\n *\n * Usage in browser-entry.ts:\n *   const rootEl = createElement(NavigationRoot, { initial: wrapped });\n *   reactRoot = hydrateRoot(document, rootEl);\n *\n * Subsequent navigations:\n *   navigateTransition(url, async () => { fetch; return wrappedElement; });\n *\n * Non-navigation renders:\n *   transitionRender(newWrappedElement);\n */\nexport function NavigationRoot({\n  initial,\n  topLoaderConfig,\n}: {\n  initial: ReactNode;\n  topLoaderConfig?: TopLoaderConfig;\n}): ReactNode {\n  const [element, setElement] = useState<ReactNode>(initial);\n  const [pendingUrl, setPendingUrl] = useState<string | null>(null);\n\n  // NOTE: We use standalone `startTransition` (imported from 'react'),\n  // NOT `useTransition`. The `useTransition` hook's `startTransition`\n  // is tied to a single fiber and tracks one async callback at a time.\n  // When two navigations overlap (click slow-page, then click dashboard),\n  // calling useTransition's startTransition twice with concurrent async\n  // callbacks corrupts React's internal hook tracking — causing\n  // \"Rendered more hooks than during the previous render.\"\n  //\n  // Standalone `startTransition` creates independent transition lanes\n  // for each call, so concurrent navigations don't interfere. We don't\n  // need useTransition's `isPending` — we track pending state via our\n  // own `pendingUrl` useState.\n  //\n  // This matches the Next.js pattern (TIM-625): \"No useTransition in\n  // the router at all — only standalone startTransition.\"\n\n  // Non-navigation render (revalidation, popstate cached replay).\n  _transitionRender = (newElement: ReactNode) => {\n    startTransition(() => {\n      setElement(newElement);\n    });\n  };\n\n  // Full navigation transition.\n  // setPendingUrl(url) is an URGENT update — React commits it before the next\n  // paint, so the pending spinner appears immediately when navigation starts.\n  // Inside startTransition: the async fetch + setElement + setPendingUrl(null)\n  // are deferred. When the transition commits, the new tree and pendingUrl=null\n  // both apply in the same React commit — making the pending→active transition\n  // atomic (no frame where pending is false but the old tree is still visible).\n  _navigateTransition = (\n    url: string,\n    perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>\n  ) => {\n    // Increment the transition counter SYNCHRONOUSLY (before startTransition\n    // schedules the async work). Each call gets a unique transId; the counter\n    // is the same globalThis singleton, so a newer call always has a higher id.\n    const counter = getTransitionCounter();\n    const transId = ++counter.id;\n\n    // NO urgent setPendingUrl here. Per-link pending state is driven by\n    // Link's own useTransition — only the clicked Link re-renders for\n    // isPending. setPendingUrl is set INSIDE startTransition so the\n    // TopLoader activates as a transition update (no full-tree re-render).\n\n    return new Promise<void>((resolve, reject) => {\n      startTransition(async () => {\n        setPendingUrl(url);\n        try {\n          const { element, decodePromise } = await perform();\n          if (counter.id !== transId) {\n            decodePromise?.catch(() => {});\n            reject(new DOMException('Navigation superseded', 'AbortError'));\n            return;\n          }\n          setElement(element);\n          if (decodePromise) await decodePromise;\n          if (counter.id === transId) {\n            setPendingUrl(null);\n            resolve();\n          } else {\n            reject(new DOMException('Navigation superseded', 'AbortError'));\n          }\n        } catch (err) {\n          if (counter.id === transId) {\n            setPendingUrl(null);\n          }\n          reject(err);\n        }\n      });\n    });\n  };\n\n  // ─── Hard navigation guard ─────────────────────────────────\n  // When a hard navigation is in progress (500 error, version skew),\n  // suspend forever to prevent React from rendering children during\n  // page teardown. This avoids \"Rendered more hooks\" crashes in\n  // CHILD components whose hook counts may shift during teardown.\n  //\n  // CRITICAL: This throw MUST come AFTER all hooks (the two\n  // useState calls above). React requires the same hooks to run on\n  // every render. If we threw before hooks, React would see 0 hooks\n  // on the re-render vs 2 hooks on the initial render — triggering\n  // the exact \"Rendered more hooks\" error we're trying to prevent.\n  //\n  // By placing it after hooks but before the return, all hooks\n  // satisfy React's rules, but the thrown thenable prevents any\n  // children from rendering. Same pattern as Next.js app-router.tsx\n  // (pushRef.mpaNavigation — also placed after all hooks).\n  if (isHardNavigating()) {\n    throw unresolvedThenable;\n  }\n\n  // Inject TopLoader alongside the element tree inside PendingNavigationProvider.\n  // The TopLoader reads pendingUrl from context to show/hide the progress bar.\n  // It is rendered only when not explicitly disabled via config.\n  const showTopLoader = topLoaderConfig?.enabled !== false;\n  const children = showTopLoader\n    ? createElement(Fragment, null, createElement(TopLoader, { config: topLoaderConfig }), element)\n    : element;\n  return createElement(PendingNavigationProvider, { value: pendingUrl }, children);\n}\n\n// ─── Public API ──────────────────────────────────────────────────\n\n/**\n * Trigger a transition render for non-navigation updates.\n * React keeps the old committed tree visible while any new Suspense\n * boundaries in the update resolve.\n *\n * Used for: applyRevalidation, popstate replay with cached payload.\n */\nexport function transitionRender(element: ReactNode): void {\n  if (_transitionRender) {\n    _transitionRender(element);\n  }\n}\n\n/**\n * Run a full navigation inside a React transition with optimistic pending URL.\n *\n * The `perform` callback runs inside `startTransition` — it should fetch the\n * RSC payload, update router state, and return the wrapped React element.\n * The pending URL shows immediately (urgent update) and reverts\n * to null when the transition commits (atomic with the new tree).\n *\n * Returns a Promise that resolves when the async work completes (note: the\n * React transition may not have committed yet, but all state updates are done).\n *\n * Used for: navigate(), refresh(), popstate with fetch.\n */\nexport function navigateTransition(\n  pendingUrl: string,\n  perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>\n): Promise<void> {\n  if (_navigateTransition) {\n    return _navigateTransition(pendingUrl, perform);\n  }\n  // Fallback: no NavigationRoot mounted (shouldn't happen in production)\n  return perform().then(() => {});\n}\n\n/**\n * Check if the NavigationRoot is mounted and ready for renders.\n * Used by browser-entry.ts to guard against renders before hydration.\n */\nexport function isNavigationRootReady(): boolean {\n  return _transitionRender !== null;\n}\n\n/**\n * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).\n *\n * When there's no RSC payload, we can't create a React root immediately —\n * `createRoot(document).render(...)` would blank the SSR HTML. Instead,\n * this sets up `_transitionRender` and `_navigateTransition` so that the\n * first client navigation triggers root creation via `createAndMount`.\n *\n * After `createAndMount` runs, NavigationRoot renders and overwrites these\n * callbacks with its real `startTransition`-based implementations.\n */\nexport function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {\n  let mounted = false;\n  const mountOnce = (element: ReactNode) => {\n    if (mounted) return;\n    mounted = true;\n    createAndMount(element);\n  };\n  _transitionRender = (element: ReactNode) => {\n    mountOnce(element);\n  };\n  _navigateTransition = async (\n    _pendingUrl: string,\n    perform: () => Promise<{ element: ReactNode; decodePromise: Promise<void> | null }>\n  ) => {\n    const { element } = await perform();\n    mountOnce(element);\n  };\n}\n"],"mappings":";;;;AAGA,SAAS,UAAU,eAAuC;CACxD,MAAM,SAAS,iBAAiB;AAChC,KAAI,CAAC,OAAQ,cAAa;AAC1B,QAAO,OAAO,gBAAgB,cAAc;;AAG9C,SAAS,cAAuB;CAC9B,MAAM,SAAS,iBAAiB;AAChC,QAAO,SAAS,OAAO,WAAW,GAAG;;AAGvC,IAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;AAuB1B,SAAgB,uBAAgC;AAC9C,QAAO,qBAAqB,WAAW,aAAa,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AEwCxE,IAAM,eAAe,OAAO,IAAI,2BAA2B;AAE3D,SAAS,kBAAsC;CAC7C,MAAM,IAAI;AACV,KAAI,CAAC,EAAE,cACL,GAAE,gBAAgB,EAAE,OAAO,OAAO;AAEpC,QAAO,EAAE;;;;;;;;AASX,SAAgB,kBAAkB,OAAsB;AACtD,kBAAiB,CAAC,QAAQ"}

package/dist/_chunks/{use-segment-params-ByGqwUuO.js → use-segment-params-CIeinIx2.js}

@@ -58,7 +58,6 @@ import React, { createElement } from "react";
 * use-pending-navigation.ts.
 */
 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;
@@ -119,35 +118,6 @@ function setNavigationState(state) {
 function getNavigationState() {
 	return _getNavStateStore().current;
 }
-/**
-* Separate context for the in-flight navigation URL. Provided by
-* NavigationRoot (urgent useState), consumed by usePendingNavigation
-* 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-segment-params.ts
 /**
@@ -176,6 +146,6 @@ function useSegmentParams(_segmentPath) {
 	return getSsrData()?.params ?? currentParams;
 }
 //#endregion
-export { setNavigationState as a, getNavigationState as i, useSegmentParams as n, useNavigationContext as o, NavigationProvider as r, usePendingNavigationUrl as s, setCurrentParams as t };
+export { setNavigationState as a, getNavigationState as i, useSegmentParams as n, useNavigationContext as o, NavigationProvider as r, setCurrentParams as t };
 
-//# sourceMappingURL=use-segment-params-ByGqwUuO.js.map
+//# sourceMappingURL=use-segment-params-CIeinIx2.js.map

package/dist/_chunks/{use-segment-params-ByGqwUuO.js.map → use-segment-params-CIeinIx2.js.map}

@@ -1 +1 @@
-{"version":3,"file":"use-segment-params-ByGqwUuO.js","names":[],"sources":["../../src/client/navigation-context.ts","../../src/client/use-segment-params.ts"],"sourcesContent":["'use client';\n\n/**\n * NavigationContext — React context for navigation state.\n *\n * Holds the current route params and pathname, updated atomically\n * with the RSC tree on each navigation. This replaces the previous\n * useSyncExternalStore approach for useSegmentParams() and usePathname(),\n * which suffered from a timing gap: the new tree could commit before\n * the external store re-renders fired, causing a frame where both\n * old and new active states were visible simultaneously.\n *\n * By wrapping the RSC payload element in NavigationProvider inside\n * renderRoot(), the context value and the element tree are passed to\n * reactRoot.render() in the same call — atomic by construction.\n * All consumers (useParams, usePathname) see the new values in the\n * same render pass as the new tree.\n *\n * During SSR, no NavigationProvider is mounted. Hooks fall back to\n * the ALS-backed getSsrData() for per-request isolation.\n *\n * IMPORTANT: createContext and useContext are NOT available in the RSC\n * environment (React Server Components use a stripped-down React).\n * The context is lazily initialized on first access, and all functions\n * that depend on these APIs are safe to call from any environment —\n * they return null or no-op when the APIs aren't available.\n *\n * SINGLETON GUARANTEE: All shared mutable state uses globalThis via\n * Symbol.for keys. The RSC client bundler can duplicate this module\n * across chunks (browser-entry graph + client-reference graph). With\n * ESM output, each chunk gets its own module scope — module-level\n * variables would create separate singleton instances per chunk.\n * globalThis guarantees a single instance regardless of duplication.\n *\n * This workaround will be removed when Rolldown ships `format: 'app'`\n * (module registry format that deduplicates like webpack/Turbopack).\n * See design/27-chunking-strategy.md.\n *\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport React, { createElement, type ReactNode } from 'react';\n\n// ---------------------------------------------------------------------------\n// Context type\n// ---------------------------------------------------------------------------\n\nexport interface NavigationState {\n  params: Record<string, string | string[]>;\n  pathname: string;\n  search: string;\n}\n\n// ---------------------------------------------------------------------------\n// Lazy context initialization\n// ---------------------------------------------------------------------------\n\n/**\n * The context is created lazily to avoid calling createContext at module\n * level. In the RSC environment, React.createContext doesn't exist —\n * calling it at import time would crash the server.\n *\n * Context instances are stored on globalThis (NOT in module-level\n * variables) because the ESM bundler can duplicate this module across\n * chunks. Module-level variables would create separate instances per\n * chunk — the provider in NavigationRoot (index chunk) would use\n * context A while the consumer in usePendingNavigation (shared chunk)\n * reads from context B. globalThis guarantees a single instance.\n *\n * See design/27-chunking-strategy.md §\"Singleton Safety\"\n *\n * NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an\n * internal helper — the public hook is `usePendingNavigation()` in\n * use-pending-navigation.ts.\n */\n\n// Symbol keys for globalThis storage — prevents collisions with user code\nconst NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');\nconst PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');\n\nfunction getOrCreateContext(): React.Context<NavigationState | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as\n    | React.Context<NavigationState | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  // createContext may not exist in the RSC environment\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<NavigationState | null>(null);\n    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the navigation context. Returns null during SSR (no provider)\n * or in the RSC environment (no context available).\n * Internal — used by useSegmentParams() and usePathname().\n */\nexport function useNavigationContext(): NavigationState | null {\n  const ctx = getOrCreateContext();\n  if (!ctx) return null;\n  // useContext may not exist in the RSC environment — caller wraps in try/catch\n  if (typeof React.useContext !== 'function') return null;\n  return React.useContext(ctx);\n}\n\n// ---------------------------------------------------------------------------\n// Provider component\n// ---------------------------------------------------------------------------\n\nexport interface NavigationProviderProps {\n  value: NavigationState;\n  children?: ReactNode;\n}\n\n/**\n * Wraps children with NavigationContext.Provider.\n *\n * Used in browser-entry.ts renderRoot to wrap the RSC payload element\n * so that navigation state updates atomically with the tree render.\n */\nexport function NavigationProvider({\n  value,\n  children,\n}: NavigationProviderProps): React.ReactElement {\n  const ctx = getOrCreateContext();\n  if (!ctx) {\n    // RSC environment — no context available. Return children as-is.\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Module-level state for renderRoot to read\n// ---------------------------------------------------------------------------\n\n/**\n * Navigation state communicated between the router and renderRoot.\n *\n * The router calls setNavigationState() before renderRoot(). The\n * renderRoot callback reads via getNavigationState() to create the\n * NavigationProvider with the correct params/pathname.\n *\n * This is NOT used by hooks directly — hooks read from React context.\n *\n * Stored on globalThis (like the context instances above) because the\n * router lives in one chunk while renderRoot lives in another. Module-\n * level variables would be separate per chunk.\n */\nconst NAV_STATE_KEY = Symbol.for('__timber_nav_state');\n\nfunction _getNavStateStore(): { current: NavigationState } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_STATE_KEY]) {\n    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/', search: '' } };\n  }\n  return g[NAV_STATE_KEY] as { current: NavigationState };\n}\n\nexport function setNavigationState(state: NavigationState): void {\n  _getNavStateStore().current = state;\n}\n\nexport function getNavigationState(): NavigationState {\n  return _getNavStateStore().current;\n}\n\n// ---------------------------------------------------------------------------\n// Pending Navigation Context (same module for singleton guarantee)\n// ---------------------------------------------------------------------------\n\n/**\n * Separate context for the in-flight navigation URL. Provided by\n * NavigationRoot (urgent useState), consumed by usePendingNavigation\n * and TopLoader. Per-link pending state uses useOptimistic instead\n * (see link-pending-store.ts).\n *\n * Uses globalThis via Symbol.for for the same reason as NavigationContext\n * above — the bundler may duplicate this module across chunks, and module-\n * level variables would create separate context instances.\n */\n\nfunction getOrCreatePendingContext(): React.Context<string | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as\n    | React.Context<string | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<string | null>(null);\n    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the pending navigation URL from context.\n * Returns null during SSR (no provider) or in the RSC environment.\n */\nexport function usePendingNavigationUrl(): string | null {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) return null;\n  if (typeof React.useContext !== 'function') return null;\n  return React.useContext(ctx);\n}\n\n/**\n * Provider for the pending navigation URL. Wraps children with\n * the pending context Provider.\n */\nexport function PendingNavigationProvider({\n  value,\n  children,\n}: {\n  value: string | null;\n  children?: ReactNode;\n}): React.ReactElement {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) {\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Navigation API transition state (optional progressive enhancement)\n// ---------------------------------------------------------------------------\n\n/**\n * Check if the browser's Navigation API has an active transition.\n *\n * When the Navigation API is available and a navigation has been intercepted\n * via event.intercept(), `navigation.transition` is non-null until the\n * handler resolves. This provides browser-native progress tracking that\n * can be used alongside the existing pendingUrl mechanism.\n *\n * Returns false when Navigation API is unavailable or no transition is active.\n */\nexport function hasNativeNavigationTransition(): boolean {\n  if (typeof window === 'undefined') return false;\n  const nav = (window as unknown as { navigation?: { transition?: unknown } }).navigation;\n  return nav?.transition != null;\n}\n","/**\n * useParams() — client-side hook for accessing route params.\n *\n * Returns the dynamic route parameters for the current URL.\n * When called with a route pattern argument, TypeScript narrows\n * the return type to the exact params shape for that route.\n *\n * Two layers of type narrowing work together:\n * 1. The generic overload here uses the Routes interface directly —\n *    `useParams<R>()` returns `Routes[R]['segmentParams']`.\n * 2. Build-time codegen generates per-route string-literal overloads\n *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).\n *\n * When the Routes interface is empty (no codegen yet), the generic\n * overload has `keyof Routes = never`, so only the fallback matches.\n *\n * During SSR, params are read from the ALS-backed SSR data context\n * (populated by ssr-entry.ts) to ensure correct per-request isolation\n * across concurrent requests with streaming Suspense.\n *\n * Reactivity: On the client, useParams() reads from NavigationContext\n * which is updated atomically with the RSC tree render. This replaces\n * the previous useSyncExternalStore approach that suffered from a\n * timing gap between tree render and store notification — causing\n * preserved layout components to briefly show stale active state.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n *\n * Design doc: design/09-typescript.md §\"Typed Routes\"\n */\n\nimport type { Routes } from '../index.js';\nimport { getSsrData } from './ssr-data.js';\nimport { currentParams, _setCurrentParams, paramsListeners } from './state.js';\nimport { useNavigationContext } from './navigation-context.js';\n\n// ---------------------------------------------------------------------------\n// Module-level subscribe/notify pattern — kept for backward compat and tests\n// ---------------------------------------------------------------------------\n\n/**\n * Subscribe to params changes.\n * Retained for backward compatibility with tests that verify the\n * subscribe/notify contract. On the client, useParams() reads from\n * NavigationContext instead.\n */\nexport function subscribe(callback: () => void): () => void {\n  paramsListeners.add(callback);\n  return () => paramsListeners.delete(callback);\n}\n\n/**\n * Get the current params snapshot (module-level fallback).\n * Used by tests and by the hook when called outside a React component.\n */\nexport function getSnapshot(): Record<string, string | string[]> {\n  return currentParams;\n}\n\n// ---------------------------------------------------------------------------\n// Framework API — called by the segment router on each navigation\n// ---------------------------------------------------------------------------\n\n/**\n * Set the current route params in the module-level store.\n *\n * Called by the router on each navigation. This updates the fallback\n * snapshot used by tests and by the hook when called outside a React\n * component (no NavigationContext available).\n *\n * On the client, the primary reactivity path is NavigationContext —\n * the router calls setNavigationState() then renderRoot() which wraps\n * the element in NavigationProvider. setCurrentParams is still called\n * for the module-level fallback.\n *\n * During SSR, params are also available via getSsrData().params\n * (ALS-backed).\n */\nexport function setCurrentParams(params: Record<string, string | string[]>): void {\n  _setCurrentParams(params);\n}\n\n/**\n * Notify all legacy subscribers that params have changed.\n *\n * Retained for backward compatibility with tests. On the client,\n * the NavigationContext + renderRoot pattern replaces this — params\n * update atomically with the tree render, so explicit notification\n * is no longer needed.\n */\nexport function notifyParamsListeners(): void {\n  for (const listener of paramsListeners) {\n    listener();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public hook\n// ---------------------------------------------------------------------------\n\n/**\n * Read the current route's dynamic params.\n *\n * The optional `_route` argument exists only for TypeScript narrowing —\n * it does not affect the runtime return value.\n *\n * On the client, reads from NavigationContext (provided by\n * NavigationProvider in renderRoot). This ensures params update\n * atomically with the RSC tree — no timing gap.\n *\n * During SSR, reads from the ALS-backed SSR data context to ensure\n * per-request isolation across concurrent requests with streaming Suspense.\n *\n * When called outside a React component (e.g., in test assertions),\n * falls back to the module-level snapshot.\n *\n * @overload Typed — when a known segment path is passed, returns the\n *   exact params shape from the generated Routes interface.\n * @overload Fallback — returns the generic params record.\n */\nexport function useSegmentParams<R extends keyof Routes>(\n  segmentPath: R\n): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;\nexport function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;\nexport function useSegmentParams(_segmentPath?: string): Record<string, string | string[]> {\n  // Try reading from NavigationContext (client-side, inside React tree).\n  // During SSR, no NavigationProvider is mounted, so this returns null.\n  // When called outside a React component, useContext throws — caught below.\n  try {\n    const navContext = useNavigationContext();\n    if (navContext !== null) {\n      return navContext.params;\n    }\n  } catch {\n    // No React dispatcher available (called outside a component).\n    // Fall through to module-level snapshot below.\n  }\n\n  // SSR path: read from ALS-backed SSR data context.\n  // Falls back to module-level currentParams for tests.\n  return getSsrData()?.params ?? currentParams;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,IAAM,cAAc,OAAO,IAAI,mBAAmB;AAClD,IAAM,kBAAkB,OAAO,IAAI,2BAA2B;AAE9D,SAAS,qBAAwE;CAC/E,MAAM,WAAY,WAAuC;AAGzD,KAAI,aAAa,KAAA,EAAW,QAAO;AAEnC,KAAI,OAAO,MAAM,kBAAkB,YAAY;EAC7C,MAAM,MAAM,MAAM,cAAsC,KAAK;AAC5D,aAAuC,eAAe;AACvD,SAAO;;;;;;;;AAUX,SAAgB,uBAA+C;CAC7D,MAAM,MAAM,oBAAoB;AAChC,KAAI,CAAC,IAAK,QAAO;AAEjB,KAAI,OAAO,MAAM,eAAe,WAAY,QAAO;AACnD,QAAO,MAAM,WAAW,IAAI;;;;;;;;AAkB9B,SAAgB,mBAAmB,EACjC,OACA,YAC8C;CAC9C,MAAM,MAAM,oBAAoB;AAChC,KAAI,CAAC,IAEH,QAAO;AAET,QAAO,cAAc,IAAI,UAAU,EAAE,OAAO,EAAE,SAAS;;;;;;;;;;;;;;;AAoBzD,IAAM,gBAAgB,OAAO,IAAI,qBAAqB;AAEtD,SAAS,oBAAkD;CACzD,MAAM,IAAI;AACV,KAAI,CAAC,EAAE,eACL,GAAE,iBAAiB,EAAE,SAAS;EAAE,QAAQ,EAAE;EAAE,UAAU;EAAK,QAAQ;EAAI,EAAE;AAE3E,QAAO,EAAE;;AAGX,SAAgB,mBAAmB,OAA8B;AAC/D,oBAAmB,CAAC,UAAU;;AAGhC,SAAgB,qBAAsC;AACpD,QAAO,mBAAmB,CAAC;;;;;;;;;;;;AAkB7B,SAAS,4BAAsE;CAC7E,MAAM,WAAY,WAAuC;AAGzD,KAAI,aAAa,KAAA,EAAW,QAAO;AACnC,KAAI,OAAO,MAAM,kBAAkB,YAAY;EAC7C,MAAM,MAAM,MAAM,cAA6B,KAAK;AACnD,aAAuC,mBAAmB;AAC3D,SAAO;;;;;;;AASX,SAAgB,0BAAyC;CACvD,MAAM,MAAM,2BAA2B;AACvC,KAAI,CAAC,IAAK,QAAO;AACjB,KAAI,OAAO,MAAM,eAAe,WAAY,QAAO;AACnD,QAAO,MAAM,WAAW,IAAI;;;;;;;;;;;;;;;;;;;AC9H9B,SAAgB,iBAAiB,QAAiD;AAChF,mBAAkB,OAAO;;AA6C3B,SAAgB,iBAAiB,cAA0D;AAIzF,KAAI;EACF,MAAM,aAAa,sBAAsB;AACzC,MAAI,eAAe,KACjB,QAAO,WAAW;SAEd;AAOR,QAAO,YAAY,EAAE,UAAU"}
+{"version":3,"file":"use-segment-params-CIeinIx2.js","names":[],"sources":["../../src/client/navigation-context.ts","../../src/client/use-segment-params.ts"],"sourcesContent":["'use client';\n\n/**\n * NavigationContext — React context for navigation state.\n *\n * Holds the current route params and pathname, updated atomically\n * with the RSC tree on each navigation. This replaces the previous\n * useSyncExternalStore approach for useSegmentParams() and usePathname(),\n * which suffered from a timing gap: the new tree could commit before\n * the external store re-renders fired, causing a frame where both\n * old and new active states were visible simultaneously.\n *\n * By wrapping the RSC payload element in NavigationProvider inside\n * renderRoot(), the context value and the element tree are passed to\n * reactRoot.render() in the same call — atomic by construction.\n * All consumers (useParams, usePathname) see the new values in the\n * same render pass as the new tree.\n *\n * During SSR, no NavigationProvider is mounted. Hooks fall back to\n * the ALS-backed getSsrData() for per-request isolation.\n *\n * IMPORTANT: createContext and useContext are NOT available in the RSC\n * environment (React Server Components use a stripped-down React).\n * The context is lazily initialized on first access, and all functions\n * that depend on these APIs are safe to call from any environment —\n * they return null or no-op when the APIs aren't available.\n *\n * SINGLETON GUARANTEE: All shared mutable state uses globalThis via\n * Symbol.for keys. The RSC client bundler can duplicate this module\n * across chunks (browser-entry graph + client-reference graph). With\n * ESM output, each chunk gets its own module scope — module-level\n * variables would create separate singleton instances per chunk.\n * globalThis guarantees a single instance regardless of duplication.\n *\n * This workaround will be removed when Rolldown ships `format: 'app'`\n * (module registry format that deduplicates like webpack/Turbopack).\n * See design/27-chunking-strategy.md.\n *\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport React, { createElement, type ReactNode } from 'react';\n\n// ---------------------------------------------------------------------------\n// Context type\n// ---------------------------------------------------------------------------\n\nexport interface NavigationState {\n  params: Record<string, string | string[]>;\n  pathname: string;\n  search: string;\n}\n\n// ---------------------------------------------------------------------------\n// Lazy context initialization\n// ---------------------------------------------------------------------------\n\n/**\n * The context is created lazily to avoid calling createContext at module\n * level. In the RSC environment, React.createContext doesn't exist —\n * calling it at import time would crash the server.\n *\n * Context instances are stored on globalThis (NOT in module-level\n * variables) because the ESM bundler can duplicate this module across\n * chunks. Module-level variables would create separate instances per\n * chunk — the provider in NavigationRoot (index chunk) would use\n * context A while the consumer in usePendingNavigation (shared chunk)\n * reads from context B. globalThis guarantees a single instance.\n *\n * See design/27-chunking-strategy.md §\"Singleton Safety\"\n *\n * NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an\n * internal helper — the public hook is `usePendingNavigation()` in\n * use-pending-navigation.ts.\n */\n\n// Symbol keys for globalThis storage — prevents collisions with user code\nconst NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');\nconst PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');\n\nfunction getOrCreateContext(): React.Context<NavigationState | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as\n    | React.Context<NavigationState | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  // createContext may not exist in the RSC environment\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<NavigationState | null>(null);\n    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the navigation context. Returns null during SSR (no provider)\n * or in the RSC environment (no context available).\n * Internal — used by useSegmentParams() and usePathname().\n */\nexport function useNavigationContext(): NavigationState | null {\n  const ctx = getOrCreateContext();\n  if (!ctx) return null;\n  // useContext may not exist in the RSC environment — caller wraps in try/catch\n  if (typeof React.useContext !== 'function') return null;\n  return React.useContext(ctx);\n}\n\n// ---------------------------------------------------------------------------\n// Provider component\n// ---------------------------------------------------------------------------\n\nexport interface NavigationProviderProps {\n  value: NavigationState;\n  children?: ReactNode;\n}\n\n/**\n * Wraps children with NavigationContext.Provider.\n *\n * Used in browser-entry.ts renderRoot to wrap the RSC payload element\n * so that navigation state updates atomically with the tree render.\n */\nexport function NavigationProvider({\n  value,\n  children,\n}: NavigationProviderProps): React.ReactElement {\n  const ctx = getOrCreateContext();\n  if (!ctx) {\n    // RSC environment — no context available. Return children as-is.\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Module-level state for renderRoot to read\n// ---------------------------------------------------------------------------\n\n/**\n * Navigation state communicated between the router and renderRoot.\n *\n * The router calls setNavigationState() before renderRoot(). The\n * renderRoot callback reads via getNavigationState() to create the\n * NavigationProvider with the correct params/pathname.\n *\n * This is NOT used by hooks directly — hooks read from React context.\n *\n * Stored on globalThis (like the context instances above) because the\n * router lives in one chunk while renderRoot lives in another. Module-\n * level variables would be separate per chunk.\n */\nconst NAV_STATE_KEY = Symbol.for('__timber_nav_state');\n\nfunction _getNavStateStore(): { current: NavigationState } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_STATE_KEY]) {\n    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/', search: '' } };\n  }\n  return g[NAV_STATE_KEY] as { current: NavigationState };\n}\n\nexport function setNavigationState(state: NavigationState): void {\n  _getNavStateStore().current = state;\n}\n\nexport function getNavigationState(): NavigationState {\n  return _getNavStateStore().current;\n}\n\n// ---------------------------------------------------------------------------\n// Pending Navigation Context (same module for singleton guarantee)\n// ---------------------------------------------------------------------------\n\n/**\n * Separate context for the in-flight navigation URL. Provided by\n * NavigationRoot (urgent useState), consumed by usePendingNavigation\n * and TopLoader. Per-link pending state uses useOptimistic instead\n * (see link-pending-store.ts).\n *\n * Uses globalThis via Symbol.for for the same reason as NavigationContext\n * above — the bundler may duplicate this module across chunks, and module-\n * level variables would create separate context instances.\n */\n\nfunction getOrCreatePendingContext(): React.Context<string | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as\n    | React.Context<string | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<string | null>(null);\n    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the pending navigation URL from context.\n * Returns null during SSR (no provider) or in the RSC environment.\n */\nexport function usePendingNavigationUrl(): string | null {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) return null;\n  if (typeof React.useContext !== 'function') return null;\n  return React.useContext(ctx);\n}\n\n/**\n * Provider for the pending navigation URL. Wraps children with\n * the pending context Provider.\n */\nexport function PendingNavigationProvider({\n  value,\n  children,\n}: {\n  value: string | null;\n  children?: ReactNode;\n}): React.ReactElement {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) {\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Navigation API transition state (optional progressive enhancement)\n// ---------------------------------------------------------------------------\n\n/**\n * Check if the browser's Navigation API has an active transition.\n *\n * When the Navigation API is available and a navigation has been intercepted\n * via event.intercept(), `navigation.transition` is non-null until the\n * handler resolves. This provides browser-native progress tracking that\n * can be used alongside the existing pendingUrl mechanism.\n *\n * Returns false when Navigation API is unavailable or no transition is active.\n */\nexport function hasNativeNavigationTransition(): boolean {\n  if (typeof window === 'undefined') return false;\n  const nav = (window as unknown as { navigation?: { transition?: unknown } }).navigation;\n  return nav?.transition != null;\n}\n","/**\n * useParams() — client-side hook for accessing route params.\n *\n * Returns the dynamic route parameters for the current URL.\n * When called with a route pattern argument, TypeScript narrows\n * the return type to the exact params shape for that route.\n *\n * Two layers of type narrowing work together:\n * 1. The generic overload here uses the Routes interface directly —\n *    `useParams<R>()` returns `Routes[R]['segmentParams']`.\n * 2. Build-time codegen generates per-route string-literal overloads\n *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).\n *\n * When the Routes interface is empty (no codegen yet), the generic\n * overload has `keyof Routes = never`, so only the fallback matches.\n *\n * During SSR, params are read from the ALS-backed SSR data context\n * (populated by ssr-entry.ts) to ensure correct per-request isolation\n * across concurrent requests with streaming Suspense.\n *\n * Reactivity: On the client, useParams() reads from NavigationContext\n * which is updated atomically with the RSC tree render. This replaces\n * the previous useSyncExternalStore approach that suffered from a\n * timing gap between tree render and store notification — causing\n * preserved layout components to briefly show stale active state.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n *\n * Design doc: design/09-typescript.md §\"Typed Routes\"\n */\n\nimport type { Routes } from '../index.js';\nimport { getSsrData } from './ssr-data.js';\nimport { currentParams, _setCurrentParams, paramsListeners } from './state.js';\nimport { useNavigationContext } from './navigation-context.js';\n\n// ---------------------------------------------------------------------------\n// Module-level subscribe/notify pattern — kept for backward compat and tests\n// ---------------------------------------------------------------------------\n\n/**\n * Subscribe to params changes.\n * Retained for backward compatibility with tests that verify the\n * subscribe/notify contract. On the client, useParams() reads from\n * NavigationContext instead.\n */\nexport function subscribe(callback: () => void): () => void {\n  paramsListeners.add(callback);\n  return () => paramsListeners.delete(callback);\n}\n\n/**\n * Get the current params snapshot (module-level fallback).\n * Used by tests and by the hook when called outside a React component.\n */\nexport function getSnapshot(): Record<string, string | string[]> {\n  return currentParams;\n}\n\n// ---------------------------------------------------------------------------\n// Framework API — called by the segment router on each navigation\n// ---------------------------------------------------------------------------\n\n/**\n * Set the current route params in the module-level store.\n *\n * Called by the router on each navigation. This updates the fallback\n * snapshot used by tests and by the hook when called outside a React\n * component (no NavigationContext available).\n *\n * On the client, the primary reactivity path is NavigationContext —\n * the router calls setNavigationState() then renderRoot() which wraps\n * the element in NavigationProvider. setCurrentParams is still called\n * for the module-level fallback.\n *\n * During SSR, params are also available via getSsrData().params\n * (ALS-backed).\n */\nexport function setCurrentParams(params: Record<string, string | string[]>): void {\n  _setCurrentParams(params);\n}\n\n/**\n * Notify all legacy subscribers that params have changed.\n *\n * Retained for backward compatibility with tests. On the client,\n * the NavigationContext + renderRoot pattern replaces this — params\n * update atomically with the tree render, so explicit notification\n * is no longer needed.\n */\nexport function notifyParamsListeners(): void {\n  for (const listener of paramsListeners) {\n    listener();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public hook\n// ---------------------------------------------------------------------------\n\n/**\n * Read the current route's dynamic params.\n *\n * The optional `_route` argument exists only for TypeScript narrowing —\n * it does not affect the runtime return value.\n *\n * On the client, reads from NavigationContext (provided by\n * NavigationProvider in renderRoot). This ensures params update\n * atomically with the RSC tree — no timing gap.\n *\n * During SSR, reads from the ALS-backed SSR data context to ensure\n * per-request isolation across concurrent requests with streaming Suspense.\n *\n * When called outside a React component (e.g., in test assertions),\n * falls back to the module-level snapshot.\n *\n * @overload Typed — when a known segment path is passed, returns the\n *   exact params shape from the generated Routes interface.\n * @overload Fallback — returns the generic params record.\n */\nexport function useSegmentParams<R extends keyof Routes>(\n  segmentPath: R\n): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;\nexport function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;\nexport function useSegmentParams(_segmentPath?: string): Record<string, string | string[]> {\n  // Try reading from NavigationContext (client-side, inside React tree).\n  // During SSR, no NavigationProvider is mounted, so this returns null.\n  // When called outside a React component, useContext throws — caught below.\n  try {\n    const navContext = useNavigationContext();\n    if (navContext !== null) {\n      return navContext.params;\n    }\n  } catch {\n    // No React dispatcher available (called outside a component).\n    // Fall through to module-level snapshot below.\n  }\n\n  // SSR path: read from ALS-backed SSR data context.\n  // Falls back to module-level currentParams for tests.\n  return getSsrData()?.params ?? currentParams;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,IAAM,cAAc,OAAO,IAAI,mBAAmB;AAGlD,SAAS,qBAAwE;CAC/E,MAAM,WAAY,WAAuC;AAGzD,KAAI,aAAa,KAAA,EAAW,QAAO;AAEnC,KAAI,OAAO,MAAM,kBAAkB,YAAY;EAC7C,MAAM,MAAM,MAAM,cAAsC,KAAK;AAC5D,aAAuC,eAAe;AACvD,SAAO;;;;;;;;AAUX,SAAgB,uBAA+C;CAC7D,MAAM,MAAM,oBAAoB;AAChC,KAAI,CAAC,IAAK,QAAO;AAEjB,KAAI,OAAO,MAAM,eAAe,WAAY,QAAO;AACnD,QAAO,MAAM,WAAW,IAAI;;;;;;;;AAkB9B,SAAgB,mBAAmB,EACjC,OACA,YAC8C;CAC9C,MAAM,MAAM,oBAAoB;AAChC,KAAI,CAAC,IAEH,QAAO;AAET,QAAO,cAAc,IAAI,UAAU,EAAE,OAAO,EAAE,SAAS;;;;;;;;;;;;;;;AAoBzD,IAAM,gBAAgB,OAAO,IAAI,qBAAqB;AAEtD,SAAS,oBAAkD;CACzD,MAAM,IAAI;AACV,KAAI,CAAC,EAAE,eACL,GAAE,iBAAiB,EAAE,SAAS;EAAE,QAAQ,EAAE;EAAE,UAAU;EAAK,QAAQ;EAAI,EAAE;AAE3E,QAAO,EAAE;;AAGX,SAAgB,mBAAmB,OAA8B;AAC/D,oBAAmB,CAAC,UAAU;;AAGhC,SAAgB,qBAAsC;AACpD,QAAO,mBAAmB,CAAC;;;;;;;;;;;;;;;;;;;ACvF7B,SAAgB,iBAAiB,QAAiD;AAChF,mBAAkB,OAAO;;AA6C3B,SAAgB,iBAAiB,cAA0D;AAIzF,KAAI;EACF,MAAM,aAAa,sBAAsB;AACzC,MAAI,eAAe,KACjB,QAAO,WAAW;SAEd;AAOR,QAAO,YAAY,EAAE,UAAU"}

package/dist/client/index.js

@@ -2,13 +2,13 @@
 import { n as classifyUrlSegment } from "../_chunks/segment-classify-BjfuctV2.js";
 import { t as getSearchParamsDefinition } from "../_chunks/registry-BI9cgCt7.js";
 import { n as getSsrData } from "../_chunks/ssr-data-DVX8S7vj.js";
-import { n as useSegmentParams, o as useNavigationContext, s as usePendingNavigationUrl } from "../_chunks/use-segment-params-ByGqwUuO.js";
+import { n as useSegmentParams, o as useNavigationContext } from "../_chunks/use-segment-params-CIeinIx2.js";
 import { t as mergePreservedSearchParams } from "../_chunks/merge-search-params-Cm1j99HC.js";
 import { n as getRouterOrNull } from "../_chunks/router-ref-B2-2kIIC.js";
 import { n as useSegmentContext } from "../_chunks/segment-context-Bg0pFbLT.js";
-import { i as unmountLinkForCurrentNavigation, n as LINK_IDLE, r as setLinkForCurrentNavigation } from "../_chunks/navigation-root-CeNTCxzS.js";
-import { t as getLinkCodec } from "../_chunks/codec-registry-G9hD5LOq.js";
-import { createContext, useActionState as useActionState$1, useContext, useEffect, useRef, useState, useTransition } from "react";
+import { t as getLinkCodec } from "../_chunks/codec-registry-DqkeAydt.js";
+import { n as usePendingNavigation } from "../_chunks/navigation-root-B5-RmsPi.js";
+import { createContext, useActionState as useActionState$1, useContext, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
 /**
@@ -44,31 +44,10 @@ var LinkStatusContext = createContext({ isPending: false });
 function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
-/**
-* Store metadata from Link's onClick for the next navigate event.
-* Called synchronously in the click handler — the navigate event
-* fires synchronously after onClick returns.
-*/
-function setNavLinkMetadata(metadata) {}
-//#endregion
-//#region src/client/navigation-api.ts
-/**
-* Returns true if the Navigation API is available in the current environment.
-* Feature-detected at runtime — no polyfill.
-*/
-function hasNavigationApi() {
-	return typeof window !== "undefined" && "navigation" in window && window.navigation != null;
-}
-/**
-* Get the Navigation API instance. Returns null if unavailable.
-* Uses type assertion — we never import Navigation API types unconditionally.
-*/
-function getNavigationApi() {
-	if (!hasNavigationApi()) return null;
-	return window.navigation;
-}
 //#endregion
 //#region src/client/link.tsx
+var LINK_PENDING = { isPending: true };
+var LINK_IDLE = { isPending: false };
 /**
 * Read the current URL's search string without requiring a React hook.
 * On the client, reads window.location.search. During SSR, reads from
@@ -269,16 +248,8 @@ var Link = function LinkImpl(props) {
 		params: segmentParams,
 		searchParams
 	});
-	const [linkStatus, setIsPending] = useState(LINK_IDLE);
-	const linkInstanceRef = useRef(null);
-	if (!linkInstanceRef.current) linkInstanceRef.current = { setIsPending };
-	else linkInstanceRef.current.setIsPending = setIsPending;
-	useEffect(() => {
-		const instance = linkInstanceRef.current;
-		return () => {
-			if (instance) unmountLinkForCurrentNavigation(instance);
-		};
-	}, []);
+	const [isPending, startTransition] = useTransition();
+	const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
 	const resolvedHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : baseHref;
 	const internal = isInternalHref(resolvedHref);
 	const handleClick = internal ? (event) => {
@@ -296,26 +267,23 @@ var Link = function LinkImpl(props) {
 		}
 		const router = getRouterOrNull();
 		if (!router) return;
-		const shouldScroll = scroll !== false;
-		setLinkForCurrentNavigation(linkInstanceRef.current);
-		if (hasNavigationApi()) {
-			setNavLinkMetadata({
-				scroll: shouldScroll,
-				linkInstance: linkInstanceRef.current
-			});
-			return;
-		}
-		if (resolvedHref.startsWith("#")) return;
-		event.preventDefault();
 		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
-		router.navigate(navHref, { scroll: shouldScroll });
+		const resolved = new URL(navHref, window.location.href);
+		if (resolved.pathname === window.location.pathname && resolved.search === window.location.search && resolved.hash) return;
+		event.preventDefault();
+		const shouldScroll = scroll !== false;
+		const absoluteHref = resolved.pathname + resolved.search;
+		startTransition(async () => {
+			await router.navigate(absoluteHref, { scroll: shouldScroll });
+		});
 	} : userOnClick;
 	const handleMouseEnter = internal && prefetch ? (event) => {
 		userOnMouseEnter?.(event);
 		const router = getRouterOrNull();
 		if (router) {
 			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;
 	return /* @__PURE__ */ jsx("a", {
@@ -330,35 +298,6 @@ var Link = function LinkImpl(props) {
 	});
 };
 //#endregion
-//#region src/client/use-pending-navigation.ts
-/**
-* Returns true while an RSC navigation is in flight.
-*
-* The pending state is true from the moment the RSC fetch starts until
-* React reconciliation completes. This includes the fetch itself,
-* RSC stream parsing, and React tree reconciliation.
-*
-* It does NOT include Suspense streaming after the shell — only the
-* initial shell reconciliation.
-*
-* ```tsx
-* 'use client'
-* import { usePendingNavigation } from '@timber-js/app/client'
-*
-* export function NavBar() {
-*   const isPending = usePendingNavigation()
-*   return (
-*     <nav className={isPending ? 'opacity-50' : ''}>
-*       <Link href="/dashboard">Dashboard</Link>
-*     </nav>
-*   )
-* }
-* ```
-*/
-function usePendingNavigation() {
-	return usePendingNavigationUrl() !== null;
-}
-//#endregion
 //#region src/client/use-router.ts
 /**
 * useRouter() — client-side hook for programmatic navigation.
@@ -481,6 +420,23 @@ function usePathname() {
 	return "/";
 }
 //#endregion
+//#region src/client/navigation-api.ts
+/**
+* Returns true if the Navigation API is available in the current environment.
+* Feature-detected at runtime — no polyfill.
+*/
+function hasNavigationApi() {
+	return typeof window !== "undefined" && "navigation" in window && window.navigation != null;
+}
+/**
+* Get the Navigation API instance. Returns null if unavailable.
+* Uses type assertion — we never import Navigation API types unconditionally.
+*/
+function getNavigationApi() {
+	if (!hasNavigationApi()) return null;
+	return window.navigation;
+}
+//#endregion
 //#region src/client/shallow-url.ts
 /**
 * Shallow URL replacement — update the browser URL bar without triggering