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

package/src/client/segment-outlet.tsx

@@ -1,33 +1,31 @@
 /**
  * SegmentOutlet — client component boundary at each layout segment.
  *
- * Replaces the post-hoc tree walking in segment-merger.ts with an explicit
- * client component at each segment boundary. Each outlet:
+ * Each layout in the segment tree is wrapped with a SegmentOutlet that:
+ * 1. Knows its segment path (prop from the server)
+ * 2. Reads from SegmentUpdateContext for partial navigation updates
+ * 3. Caches its rendered content in a ref across navigations
  *
- * 1. Knows its own segment path (prop from the server)
- * 2. Caches its children in a ref across navigations
- * 3. When `keepCurrent` is true (partial navigation, this segment skipped),
- *    returns the previously cached children — layout state is preserved
- * 4. When `keepCurrent` is false (full navigation or this segment changed),
- *    stores and renders the new children
+ * On full navigation: receives new children via props, caches and renders them.
+ * On partial navigation (this segment skipped): the context map has no entry
+ * for this path, so the outlet returns cached content — preserving layout state.
+ * On partial navigation (this segment updated): the context map has content
+ * for this path, so the outlet renders the update.
  *
- * This eliminates the need for client-side element tree walking, which
- * breaks on real RSC trees due to opaque client component lazy refs,
- * Suspense thenables, and AccessGate wrappers.
+ * Uses React context instead of useSyncExternalStore to stay compatible
+ * with concurrent rendering (transitions). All outlets re-render when the
+ * context value changes, but each bails out quickly if its segment has
+ * no update — same approach as Next.js LayoutRouter.
  *
- * Architecture is similar to Next.js's `<LayoutRouter>` client component —
- * each layout boundary is an explicit client component that manages its
- * own subtree. See design/19-client-navigation.md.
- *
- * Security: This is a performance optimization only. The server always
- * runs all access.ts files regardless of segment skipping. A fabricated
- * keepCurrent prop can only cause stale layouts — never auth bypass.
+ * Security: performance optimization only. The server always runs all
+ * access.ts files regardless of segment skipping.
  * See design/13-security.md §"State tree manipulation".
  */
 
 'use client';
 
-import { useRef, type ReactNode } from 'react';
+import { useContext, useRef, type ReactNode } from 'react';
+import { SegmentUpdateContext } from './segment-update-context.js';
 
 export interface SegmentOutletProps {
   /**
@@ -38,17 +36,6 @@ export interface SegmentOutletProps {
    */
   segmentPath: string;
 
-  /**
-   * When true, the outlet returns its previously cached children instead
-   * of rendering the new children prop. Set by the server when this
-   * segment was skipped (the client already has the layout mounted).
-   *
-   * On the first render (SSR/hydration), this is always false — there's
-   * no cached content yet. On subsequent partial navigations, the server
-   * sets this to true for segments it skipped rendering.
-   */
-  keepCurrent?: boolean;
-
   /** The segment's React subtree (layout + inner content). */
   children: ReactNode;
 }
@@ -56,31 +43,35 @@ export interface SegmentOutletProps {
 /**
  * Client component boundary at each layout segment in the element tree.
  *
- * On full navigation: receives new children, stores them, renders them.
- * On partial navigation (keepCurrent=true): ignores children prop,
- * returns previously stored content — React reconciles the same elements,
- * preserving all client component state in the layout subtree.
+ * On full navigation (context map is empty): renders children, caches in ref.
+ * On partial navigation: checks the context map for an update at segmentPath.
+ *   - Update found → renders update, caches in ref.
+ *   - No update → returns cached content (layout state preserved).
  *
- * React preserves the ref across `reactRoot.render()` calls because:
- * - SegmentOutlet has a stable type (client component module reference)
- * - It appears at the same tree position on every navigation
- * - React reconciles same-type, same-position → instance preserved
+ * React preserves component instances across reactRoot.render() calls
+ * when the same type appears at the same tree position. The ref persists
+ * across navigations because SegmentOutlet is reconciled, not remounted.
  */
-export function SegmentOutlet({
-  segmentPath: _segmentPath,
-  keepCurrent = false,
-  children,
-}: SegmentOutletProps) {
-  // Store content in a ref to avoid triggering re-renders on cache updates.
-  // The ref persists across reactRoot.render() calls because React reconciles
-  // the same component type at the same tree position.
+export function SegmentOutlet({ segmentPath, children }: SegmentOutletProps) {
+  const updates = useContext(SegmentUpdateContext);
   const contentRef = useRef<ReactNode>(null);
 
-  if (!keepCurrent) {
-    // Full render or this segment was re-rendered — store and render new content
+  const update = updates.get(segmentPath);
+
+  if (update !== undefined) {
+    contentRef.current = update;
+    return update;
+  }
+
+  if (contentRef.current === null) {
+    contentRef.current = children;
+    return children;
+  }
+
+  if (children !== contentRef.current) {
     contentRef.current = children;
+    return children;
   }
-  // else: keepCurrent=true — return previously cached content
 
   return contentRef.current;
 }

package/src/client/segment-update-context.ts

@@ -0,0 +1,42 @@
+/**
+ * SegmentUpdateContext — React context for partial navigation updates.
+ *
+ * During partial navigation (server skips unchanged sync layouts), the
+ * router builds a Map of segment path → ReactNode updates and passes it
+ * as the context value. Mounted SegmentOutlet components read from this
+ * context to decide whether to render the update or their cached content.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. 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 — a bare createContext
+ * at module level would create separate instances per chunk. globalThis
+ * guarantees a single instance regardless of duplication.
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export const EMPTY_SEGMENT_UPDATES = new Map<string, ReactNode>();
+
+const CTX_KEY = Symbol.for('__timber_segment_update_ctx');
+
+function getOrCreateContext(): React.Context<Map<string, ReactNode>> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<Map<string, ReactNode>>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<Map<string, ReactNode>>(EMPTY_SEGMENT_UPDATES);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  // RSC environment — createContext not available. Return a dummy that
+  // won't be used (outlets only render on the client).
+  return undefined as unknown as React.Context<Map<string, ReactNode>>;
+}
+
+export const SegmentUpdateContext = getOrCreateContext();

package/src/client/use-search-params.ts

@@ -4,9 +4,12 @@
  * Returns a read-only URLSearchParams instance reflecting the current
  * URL's query string. Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.search, provided for
- * Next.js API compatibility (libraries like nuqs import useSearchParams
- * from next/navigation).
+ * On the client, reads from NavigationContext which is updated atomically
+ * with the RSC tree render. This replaces the previous useSyncExternalStore
+ * approach which read window.location.search directly — causing React to
+ * detect external store tearing during transitions and fall back to
+ * synchronous rendering (renderRootSync instead of renderRootConcurrent),
+ * blocking the main thread and freezing animations.
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the
@@ -15,42 +18,14 @@
  * During SSR, reads the request search params from the SSR ALS context
  * (populated by ssr-entry.ts) instead of window.location.
  *
- * All mutable state is delegated to client/state.ts for singleton guarantees.
- * See design/18-build-system.md §"Singleton State Registry"
+ * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 
-import { useSyncExternalStore } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { useNavigationContext } from './navigation-context.js';
 import { cachedSearch, cachedSearchParams, _setCachedSearch } from './state.js';
 
-function getSearch(): string {
-  if (typeof window !== 'undefined') return window.location.search;
-  const data = getSsrData();
-  if (!data) return '';
-  const sp = new URLSearchParams(data.searchParams);
-  const str = sp.toString();
-  return str ? `?${str}` : '';
-}
-
-function getServerSearch(): string {
-  const data = getSsrData();
-  if (!data) return '';
-  const sp = new URLSearchParams(data.searchParams);
-  const str = sp.toString();
-  return str ? `?${str}` : '';
-}
-
-function subscribe(callback: () => void): () => void {
-  window.addEventListener('popstate', callback);
-  return () => window.removeEventListener('popstate', callback);
-}
-
-// Cache the last search string and its parsed URLSearchParams to avoid
-// creating a new object on every render when the URL hasn't changed.
-// State lives in client/state.ts for singleton guarantees.
-
-function getSearchParams(): URLSearchParams {
-  const search = getSearch();
+function getSearchParams(search: string): URLSearchParams {
   if (search !== cachedSearch) {
     const params = new URLSearchParams(search);
     _setCachedSearch(search, params);
@@ -59,20 +34,26 @@ function getSearchParams(): URLSearchParams {
   return cachedSearchParams;
 }
 
-function getServerSearchParams(): URLSearchParams {
-  const data = getSsrData();
-  return data ? new URLSearchParams(data.searchParams) : new URLSearchParams();
-}
-
 /**
  * Read the current URL search params.
  *
  * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 export function useSearchParams(): URLSearchParams {
-  // useSyncExternalStore needs a primitive snapshot for comparison.
-  // We use the raw search string as the snapshot, then return the
-  // parsed URLSearchParams.
-  useSyncExternalStore(subscribe, getSearch, getServerSearch);
-  return typeof window !== 'undefined' ? getSearchParams() : getServerSearchParams();
+  try {
+    const navContext = useNavigationContext();
+    if (navContext !== null) {
+      return getSearchParams(navContext.search);
+    }
+  } catch {
+    // No React dispatcher available (called outside a component).
+  }
+
+  // SSR path: read from ALS-backed SSR data context.
+  const ssrData = getSsrData();
+  if (ssrData) return new URLSearchParams(ssrData.searchParams);
+
+  // Final fallback: window.location (tests, edge cases).
+  if (typeof window !== 'undefined') return getSearchParams(window.location.search);
+  return new URLSearchParams();
 }

package/src/server/route-element-builder.ts

@@ -44,12 +44,37 @@ import {
 import type { DenyPageEntry } from './deny-boundary.js';
 import { resolveSlotElement } from './slot-resolver.js';
 import { SegmentProvider } from '../client/segment-context.js';
+import { SegmentOutlet } from '../client/segment-outlet.js';
 
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
 import { shouldSkipSegment } from './state-tree-diff.js';
 import { loadModule } from './safe-load.js';
 
+/**
+ * Replace the outermost SegmentOutlet in a partial payload with its
+ * SegmentProvider child. Walks through AccessGate wrappers (which sit
+ * outside SegmentOutlet) to find the outlet.
+ */
+function replaceOutermostSegmentOutlet(
+  element: React.ReactElement,
+  replacement: React.ReactElement
+): React.ReactElement {
+  if (element.type === SegmentOutlet) {
+    return replacement;
+  }
+  // AccessGate wraps outside SegmentOutlet — recurse through it.
+  const props = element.props as Record<string, unknown>;
+  if (element.type === AccessGate && props.children) {
+    const inner = replaceOutermostSegmentOutlet(props.children as React.ReactElement, replacement);
+    return createElement(element.type as React.FunctionComponent<Record<string, unknown>>, {
+      ...props,
+      children: inner,
+    });
+  }
+  return element;
+}
+
 // ─── Client Reference Detection ──────────────────────────────────────────
 
 /**
@@ -445,6 +470,12 @@ export async function buildRouteElement(
   // Without this guard, skipping the innermost layout causes the merger
   // to drop the layout entirely and replace it with just the page.
   let hasRenderedLayoutBelow = false;
+  let outermostSegmentProvider: React.ReactElement | null = null;
+  // Track whether any rendered inner layout also exists in the client's
+  // state tree. This prevents cross-section skipping: e.g., navigating
+  // from /(group-a) to /dashboard shouldn't skip root "/" because the
+  // client has no mounted outlet at "/dashboard".
+  let innerRenderedInClientTree = false;
 
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
@@ -461,10 +492,14 @@ export async function buildRouteElement(
     // - Route groups are never skipped because sibling groups share the
     //   same urlPath (e.g., /(marketing) and /(app) both have "/"),
     //   which would cause the wrong cached layout to be reused
+    // - At least one inner rendered layout must exist in the client's
+    //   state tree, ensuring the client has a mounted outlet to receive
+    //   the partial payload
     const skip =
       shouldSkipSegment(segment.urlPath, layoutComponent, isLeaf, clientStateTree ?? null) &&
       hasRenderedLayoutBelow &&
-      segment.segmentType !== 'group';
+      segment.segmentType !== 'group' &&
+      innerRenderedInClientTree;
 
     if (skip) {
       // Skip this segment's layout/error boundaries — the client uses its cached version.
@@ -496,6 +531,17 @@ export async function buildRouteElement(
     // a rendered layout below them and can safely be skipped.
     if (layoutComponent) {
       hasRenderedLayoutBelow = true;
+      // Use segmentId for the client state tree check. Route groups share
+      // their parent's urlPath (both "/"), but their segmentId includes
+      // the group name (e.g., "/(group-a)"), so the check correctly
+      // fails when the client has never visited that group.
+      const outletKey =
+        segment.segmentType === 'group'
+          ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
+          : segment.urlPath;
+      if (clientStateTree?.has(outletKey)) {
+        innerRenderedInClientTree = true;
+      }
     }
 
     // Wrap with error boundaries from this segment (inside layout).
@@ -585,12 +631,24 @@ export async function buildRouteElement(
         });
       }
 
-      element = h(SegmentProvider, {
+      const segmentProviderElement = h(SegmentProvider, {
         segments: segmentPath,
         segmentId,
         parallelRouteKeys,
         children: layoutElement,
       });
+
+      element = h(SegmentOutlet, {
+        segmentPath: segmentId,
+        children: segmentProviderElement,
+      });
+
+      // Track the SegmentProvider for the outermost rendered layout.
+      // On partial navigation (segments skipped above), the client already
+      // has a SegmentOutlet mounted at this position. Sending another one
+      // in the payload causes double-wrapping and infinite context recursion.
+      // We'll strip the outermost SegmentOutlet after the loop.
+      outermostSegmentProvider = segmentProviderElement;
     }
 
     // Wrap in AccessGate OUTSIDE the layout.
@@ -611,6 +669,15 @@ export async function buildRouteElement(
     }
   }
 
+  // On partial navigation (some segments skipped), the client already has a
+  // SegmentOutlet mounted at the outermost non-skipped segment's position.
+  // Sending another SegmentOutlet in the payload causes double-wrapping —
+  // the inner outlet reads the same context update and recurses infinitely.
+  // Replace the outermost SegmentOutlet with just its SegmentProvider child.
+  if (skippedSegments.length > 0 && outermostSegmentProvider) {
+    element = replaceOutermostSegmentOutlet(element, outermostSegmentProvider);
+  }
+
   return {
     element,
     headElements: headElements as HeadElement[],

package/src/server/rsc-entry/helpers.ts

@@ -180,32 +180,36 @@ export function buildSegmentInfo(
     component: (...args: unknown[]) => unknown;
     segment: ManifestSegmentNode;
   }>
-): Array<{ path: string; isAsync: boolean }> {
+): Array<{ path: string; segmentId?: string; isAsync: boolean }> {
   const layoutBySegment = new Map(
     layoutComponents.map(({ component, segment }) => [segment, component])
   );
 
-  // Deduplicate by path — route groups are transparent and share their
-  // parent's urlPath. When a group has its own layout, update the entry
-  // to reflect the group's async status (the layout is what matters for
-  // segment diffing). Without dedup, the state tree would contain
-  // duplicate paths that break the server's skip logic.
-  const byPath = new Map<string, { path: string; isAsync: boolean }>();
+  const result: Array<{ path: string; segmentId?: string; isAsync: boolean }> = [];
 
   for (const segment of segments) {
     const component = layoutBySegment.get(segment);
     const isAsync = component?.constructor?.name === 'AsyncFunction';
 
-    const existing = byPath.get(segment.urlPath);
-    if (!existing) {
-      byPath.set(segment.urlPath, { path: segment.urlPath, isAsync });
-    } else if (component) {
-      // Group with a layout overrides the parent entry's async status
-      existing.isAsync = isAsync;
+    // Compute segmentId — matches the key used by SegmentOutlet.
+    // Route groups share their parent's urlPath, so include the group
+    // name to disambiguate (e.g., "/(marketing)" vs "/").
+    const segmentId =
+      segment.segmentType === 'group'
+        ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
+        : segment.urlPath;
+
+    const entry: { path: string; segmentId?: string; isAsync: boolean } = {
+      path: segment.urlPath,
+      isAsync,
+    };
+    if (segmentId !== segment.urlPath) {
+      entry.segmentId = segmentId;
     }
+    result.push(entry);
   }
 
-  return Array.from(byPath.values());
+  return result;
 }
 
 /**

package/src/server/state-tree-diff.ts

@@ -45,12 +45,19 @@ export function parseClientStateTree(req: Request): Set<string> | null {
  * Determine whether a segment's layout rendering can be skipped.
  *
  * A segment is skipped when ALL of the following are true:
- * 1. The client has the segment in its state tree (clientSegments contains urlPath)
- * 2. The layout is sync (not an async function — async layouts always re-render)
- * 3. The segment is NOT the leaf (pages are never cached across navigations)
+ * 1. The client sent a state tree (clientSegments is non-null)
+ * 2. The client has this segment cached (clientSegments contains urlPath)
+ * 3. The segment has a layout (otherwise nothing to skip)
+ * 4. The layout is sync (not an async function — async layouts may depend
+ *    on per-request data and must always re-render)
+ * 5. The segment is NOT the leaf (pages are never cached across navigations)
+ *
+ * Additional constraints enforced by the caller (buildRouteElement):
+ * - Must have a rendered layout below (so SegmentOutlet has content to show)
+ * - Route groups are never skipped (siblings share urlPath)
  *
  * Access.ts still runs for skipped segments — this is enforced by the caller
- * (buildRouteElement) which runs all access checks before building the tree.
+ * which wraps with AccessGate regardless of skip status.
  *
  * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
  * @param layoutComponent - The loaded layout component function
@@ -58,23 +65,20 @@ export function parseClientStateTree(req: Request): Set<string> | null {
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
 export function shouldSkipSegment(
-  _urlPath: string,
-  _layoutComponent: ((...args: unknown[]) => unknown) | undefined,
-  _isLeaf: boolean,
-  _clientSegments: Set<string> | null
+  urlPath: string,
+  layoutComponent: ((...args: unknown[]) => unknown) | undefined,
+  isLeaf: boolean,
+  clientSegments: Set<string> | null
 ): boolean {
-  // DISABLED: Client-side segment merging via React element tree walking
-  // is too fragile for production. The merger's replaceInnerSegment relies
-  // on walking RSC-decoded element trees to find SegmentProvider boundaries,
-  // but production trees contain structures the walker can't handle:
-  // Suspense wrappers, error boundaries, AccessGate components, React lazy
-  // refs, and client component module references.
-  //
-  // The merger infrastructure (segment-merger.ts, element cache, state tree
-  // filtering) is in place and tested. Re-enable when the merger can handle
-  // real RSC element trees — likely requires a SegmentOutlet client component
-  // approach instead of post-hoc element tree walking.
-  //
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  return false;
+  if (!clientSegments) return false;
+  if (!clientSegments.has(urlPath)) return false;
+  if (!layoutComponent) return false;
+  if (isLeaf) return false;
+
+  // Async layouts always re-render — they may depend on per-request data
+  // (cookies, headers, database queries) that changes between navigations.
+  // constructor.name check: AsyncFunction.name === 'AsyncFunction'
+  if (layoutComponent.constructor.name === 'AsyncFunction') return false;
+
+  return true;
 }

package/dist/_chunks/cli-schema-sync-4HcQIziG.js

@@ -1,2 +0,0 @@
-import { i as runSchemaSync } from "./cli-schema-sync-VcCf1TFY.js";
-export { runSchemaSync };

package/dist/_chunks/navigation-root-Ds_hDtRW.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"navigation-root-Ds_hDtRW.js","names":[],"sources":["../../src/client/link-pending-store.ts","../../src/client/top-loader.tsx","../../src/client/navigation-root.tsx"],"sourcesContent":["/**\n * Link Pending Store — per-link optimistic pending state.\n *\n * Tracks which link instance is currently navigating so that only the\n * clicked link shows pending. Uses `useOptimistic` from React 19 —\n * the optimistic value (isPending=true) is set inside NavigationRoot's\n * async startTransition so it persists for the duration of the RSC\n * fetch, then auto-reverts to idle when the transition settles.\n *\n * Flow:\n * 1. Link click → setLinkForCurrentNavigation(instance) stores the ref\n * 2. NavigationRoot startTransition → activateLinkPending() calls\n *    instance.setIsPending(LINK_PENDING) inside the async transition\n * 3. Transition settles → useOptimistic auto-reverts to LINK_IDLE\n *\n * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys because\n * the RSC client bundler can duplicate this module across chunks.\n *\n * See design/19-client-navigation.md §\"Per-Link Pending State\"\n */\n\nimport type { LinkStatus } from './use-link-status.js';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface LinkPendingInstance {\n  setIsPending: (status: LinkStatus) => void;\n}\n\n// ─── Constants ───────────────────────────────────────────────────\n\nconst LINK_PENDING_KEY = Symbol.for('__timber_link_pending');\n\n/** Status object: link navigation in flight */\nexport const LINK_PENDING: LinkStatus = { isPending: true };\n\n/** Status object: link idle */\nexport const LINK_IDLE: LinkStatus = { isPending: false };\n\n// ─── Singleton Storage ───────────────────────────────────────────\n\nfunction getStore(): { current: LinkPendingInstance | null } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[LINK_PENDING_KEY]) {\n    g[LINK_PENDING_KEY] = { current: null };\n  }\n  return g[LINK_PENDING_KEY] as { current: LinkPendingInstance | null };\n}\n\n// ─── Public API ──────────────────────────────────────────────────\n\n/**\n * Register the link instance that initiated the current navigation.\n * Called from Link's click handler. Does NOT call setIsPending —\n * that happens inside NavigationRoot's startTransition via\n * activateLinkPending().\n *\n * Resets the previous link to idle immediately (the old link's\n * useOptimistic reverts since its transition already settled).\n */\nexport function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {\n  const store = getStore();\n  store.current = link;\n}\n\n/**\n * Activate pending state on the current link instance.\n * MUST be called inside NavigationRoot's async startTransition —\n * this is what makes useOptimistic persist for the navigation duration.\n */\nexport function activateLinkPending(): void {\n  const store = getStore();\n  store.current?.setIsPending(LINK_PENDING);\n}\n\n/**\n * Reset the current link's pending state. With useOptimistic this is\n * handled automatically when the transition settles. Kept for callers\n * that explicitly need to clear on error paths.\n */\nexport function resetLinkPending(): void {\n  const store = getStore();\n  if (store.current) {\n    store.current.setIsPending(LINK_IDLE);\n    store.current = null;\n  }\n}\n\n/**\n * @deprecated No longer needed with useOptimistic. Kept for callers.\n */\nexport function getCurrentNavId(): number {\n  return 0;\n}\n\n/**\n * Clean up the link pending store entirely.\n */\nexport function clearLinkPendingSetter(): void {\n  getStore().current = null;\n}\n\n/**\n * Unmount a link instance from navigation tracking.\n */\nexport function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void {\n  const store = getStore();\n  if (store.current === link) {\n    store.current = null;\n  }\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 { usePendingNavigationUrl } from './navigation-context.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  const pendingUrl = usePendingNavigationUrl();\n  // Navigation is pending when the React-based pending URL is set.\n  // pendingUrl is set as an urgent update in navigateTransition() —\n  // React commits it before the next paint, so the TopLoader appears\n  // immediately when a real RSC navigation starts.\n  //\n  // We intentionally do NOT check hasNativeNavigationTransition() here.\n  // The Navigation API's transition is active for ALL intercepted\n  // navigations, including shallow URL updates (nuqs search param\n  // changes with shallow: true) and prevented navigations. Those\n  // briefly set navigation.transition via event.intercept() but do\n  // NOT trigger RSC fetches — showing the TopLoader would be incorrect.\n  // pendingUrl is the authoritative signal for \"we're fetching RSC data.\"\n  const isPending = pendingUrl !== null;\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 { activateLinkPending, resetLinkPending } from './link-pending-store.js';\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  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => 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 = (url: string, perform: () => Promise<ReactNode>) => {\n    // Urgent: show pending state immediately (for TopLoader / usePendingNavigation)\n    setPendingUrl(url);\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    return new Promise<void>((resolve, reject) => {\n      startTransition(async () => {\n        // Activate per-link pending state inside this async transition.\n        // useOptimistic persists the isPending=true value for the duration\n        // of this transition, then auto-reverts when it settles.\n        activateLinkPending();\n        try {\n          const newElement = await perform();\n          // Only commit state if this is still the active navigation.\n          // A superseded transition's updates must be dropped entirely.\n          if (counter.id === transId) {\n            setElement(newElement);\n            setPendingUrl(null);\n            resolve();\n          } else {\n            // Stale transition — a newer navigation has superseded this one.\n            // Reject so the caller (navigate/refresh/handlePopState) doesn't\n            // run post-transition side effects (applyHead, scroll, event\n            // dispatch) with stale data. All callers catch AbortError.\n            reject(new DOMException('Navigation superseded', 'AbortError'));\n          }\n        } catch (err) {\n          // Only clear pending if this is still the active navigation.\n          if (counter.id === transId) {\n            setPendingUrl(null);\n            resetLinkPending();\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<ReactNode>\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 (_pendingUrl: string, perform: () => Promise<ReactNode>) => {\n    const element = await perform();\n    mountOnce(element);\n  };\n}\n"],"mappings":";;;AA+BA,IAAM,mBAAmB,OAAO,IAAI,wBAAwB;;AAM5D,IAAa,YAAwB,EAAE,WAAW,OAAO;AAIzD,SAAS,WAAoD;CAC3D,MAAM,IAAI;AACV,KAAI,CAAC,EAAE,kBACL,GAAE,oBAAoB,EAAE,SAAS,MAAM;AAEzC,QAAO,EAAE;;;;;;;;;;;AAcX,SAAgB,4BAA4B,MAAwC;CAClF,MAAM,QAAQ,UAAU;AACxB,OAAM,UAAU;;;;;AA2ClB,SAAgB,gCAAgC,MAAiC;CAC/E,MAAM,QAAQ,UAAU;AACxB,KAAI,MAAM,YAAY,KACpB,OAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AE7BpB,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-Du7u25cK.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-segment-params-Du7u25cK.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}\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: '/' } };\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,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,EAAE;AAE/D,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;;;;;;;;;;;;;;;;;;;AC7H9B,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"}