@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/dist/client/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","names":[],"sources":["../../src/client/segment-cache.ts","../../src/client/history.ts","../../src/client/rsc-fetch.ts","../../src/client/router.ts","../../src/client/use-search-params.ts"],"sourcesContent":["// Segment Cache — stores the mounted segment tree and prefetched payloads\n// See design/19-client-navigation.md for architecture details.\n\n// ─── Types ───────────────────────────────────────────────────────\n\n/** A prefetched RSC result with optional segment metadata. */\nexport interface PrefetchResult {\n  payload: unknown;\n  /** Segment metadata from X-Timber-Segments header for populating the segment cache. */\n  segmentInfo?: SegmentInfo[] | null;\n  /** Route params from X-Timber-Params header for populating useSegmentParams(). */\n  params?: Record<string, string | string[]> | null;\n  /** Segment paths skipped by the server (for client-side merging). */\n  skippedSegments?: string[] | null;\n}\n\n/**\n * A node in the client-side segment tree. Each node represents a mounted\n * layout or page segment with its RSC flight payload.\n */\nexport interface SegmentNode {\n  /** The segment's URL pattern (e.g., \"/\", \"/dashboard\", \"/projects/[id]\") */\n  segment: string;\n  /** The RSC flight payload for this segment (opaque to the cache) */\n  payload: unknown;\n  /** Whether the segment is async (async layouts always re-render on navigation) */\n  isAsync: boolean;\n  /** Child segments keyed by segment path */\n  children: Map<string, SegmentNode>;\n}\n\n/**\n * Serialized state tree sent via X-Timber-State-Tree header.\n * Only sync segments are included — async segments always re-render.\n */\nexport interface StateTree {\n  segments: string[];\n}\n\n// ─── Segment Cache ───────────────────────────────────────────────\n\n/**\n * Maintains the client-side segment tree representing currently mounted\n * layouts and pages. Used for navigation reconciliation — the router diffs\n * new routes against this tree to determine which segments to re-fetch.\n */\nexport class SegmentCache {\n  private root: SegmentNode | undefined;\n\n  get(segment: string): SegmentNode | undefined {\n    if (segment === '/' || segment === this.root?.segment) {\n      return this.root;\n    }\n    return undefined;\n  }\n\n  set(segment: string, node: SegmentNode): void {\n    if (segment === '/' || !this.root) {\n      this.root = node;\n    }\n  }\n\n  clear(): void {\n    this.root = undefined;\n  }\n\n  /**\n   * Serialize the mounted segment tree for the X-Timber-State-Tree header.\n   * Only includes sync segments — async segments are excluded because the\n   * server must always re-render them (they may depend on request context).\n   *\n   * When mergeableFilter is provided, only segments whose paths are in the\n   * set are included. This ensures the server only skips segments that the\n   * client can actually merge (i.e., segments whose cached element tree\n   * contains an inner SegmentProvider the merger can splice into).\n   *\n   * This is a performance optimization only, NOT a security boundary.\n   * The server always runs all access.ts files regardless of the state tree.\n   */\n  serializeStateTree(mergeableFilter?: Set<string>): StateTree {\n    const segments: string[] = [];\n    if (this.root) {\n      collectSyncSegments(this.root, segments, mergeableFilter);\n    }\n    return { segments };\n  }\n}\n\n/** Recursively collect sync segment paths from the tree */\nfunction collectSyncSegments(\n  node: SegmentNode,\n  out: string[],\n  mergeableFilter?: Set<string>\n): void {\n  if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) {\n    out.push(node.segment);\n  }\n  for (const child of node.children.values()) {\n    collectSyncSegments(child, out, mergeableFilter);\n  }\n}\n\n// ─── Segment Tree Builder ────────────────────────────────────────\n\n/**\n * Segment metadata from the server, sent via X-Timber-Segments header.\n * Describes a rendered segment's path and whether it's async.\n */\nexport interface SegmentInfo {\n  path: string;\n  /** Outlet key — includes route group name when applicable (e.g., \"/(marketing)\"). */\n  segmentId?: string;\n  isAsync: boolean;\n}\n\n/**\n * Build a SegmentNode tree from flat segment metadata.\n *\n * Takes an ordered list of segment descriptors (root → leaf) from the\n * server's X-Timber-Segments header and constructs the hierarchical\n * tree structure that SegmentCache expects.\n *\n * Each segment is nested as a child of the previous one, forming a\n * linear chain from root to leaf. The leaf segment (page) is excluded\n * from the tree — pages are never cached across navigations.\n */\nexport function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefined {\n  // Need at least a root segment to build a tree\n  if (segments.length === 0) return undefined;\n\n  // Exclude the leaf (page) — pages always re-render on navigation.\n  // Only layouts are cached in the segment tree.\n  const layouts = segments.length > 1 ? segments.slice(0, -1) : segments;\n\n  let root: SegmentNode | undefined;\n  let parent: SegmentNode | undefined;\n\n  for (const info of layouts) {\n    const id = info.segmentId ?? info.path;\n    const node: SegmentNode = {\n      segment: id,\n      payload: null,\n      isAsync: info.isAsync,\n      children: new Map(),\n    };\n\n    if (!root) {\n      root = node;\n    }\n\n    if (parent) {\n      parent.children.set(id, node);\n    }\n\n    parent = node;\n  }\n\n  return root;\n}\n\n// ─── Prefetch Cache ──────────────────────────────────────────────\n\ninterface PrefetchEntry {\n  result: PrefetchResult;\n  expiresAt: number;\n}\n\n/**\n * Short-lived cache for hover-triggered prefetches. Entries expire after\n * 30 seconds. When a link is clicked, the prefetched payload is consumed\n * (moved to the history stack) and removed from this cache.\n *\n * timber.js does NOT prefetch on viewport intersection — only explicit\n * hover on <Link prefetch> triggers a prefetch.\n */\nexport class PrefetchCache {\n  private static readonly TTL_MS = 30_000;\n  private entries = new Map<string, PrefetchEntry>();\n\n  set(url: string, result: PrefetchResult): void {\n    this.entries.set(url, {\n      result,\n      expiresAt: Date.now() + PrefetchCache.TTL_MS,\n    });\n  }\n\n  get(url: string): PrefetchResult | undefined {\n    const entry = this.entries.get(url);\n    if (!entry) return undefined;\n    if (Date.now() >= entry.expiresAt) {\n      this.entries.delete(url);\n      return undefined;\n    }\n    return entry.result;\n  }\n\n  /** Get and remove the entry (used when navigation consumes a prefetch) */\n  consume(url: string): PrefetchResult | undefined {\n    const result = this.get(url);\n    if (result !== undefined) {\n      this.entries.delete(url);\n    }\n    return result;\n  }\n}\n","// History Stack — stores RSC payloads by URL for instant back/forward navigation\n// See design/19-client-navigation.md § History Stack\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface HistoryEntry {\n  /** The complete segment tree payload at the time of navigation */\n  payload: unknown;\n  /**\n   * Route params for this page (for useSegmentParams). Every entry that can\n   * be replayed must carry them — the initial SSR entry gets them from the\n   * server-embedded __timber_params, navigation entries from X-Timber-Params,\n   * and revalidation overwrites preserve the current state (TIM-1037).\n   */\n  params?: Record<string, string | string[]> | null;\n}\n\n// ─── History Stack ───────────────────────────────────────────────\n\n/**\n * Session-lived history stack keyed by URL. Enables instant back/forward\n * navigation without a server roundtrip.\n *\n * On forward navigation, the new page's payload is pushed onto the stack.\n * On popstate, the cached payload is replayed instantly.\n *\n * Entries are keyed by pathname + search. Used with the History API\n * fallback and the Navigation API.\n *\n * Scroll positions are stored in history.state or Navigation API entry\n * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.\n *\n * Entries persist for the session duration (no expiry) and are cleared\n * when the tab is closed — matching browser back-button behavior.\n */\nexport class HistoryStack {\n  private entries = new Map<string, HistoryEntry>();\n\n  push(url: string, entry: HistoryEntry): void {\n    this.entries.set(url, entry);\n  }\n\n  get(url: string): HistoryEntry | undefined {\n    return this.entries.get(url);\n  }\n\n  has(url: string): boolean {\n    return this.entries.has(url);\n  }\n}\n","/**\n * RSC Fetch — handles fetching and parsing RSC Flight payloads.\n *\n * Extracted from router.ts to keep both files under the 500-line limit.\n * This module handles:\n * - Cache-busting URL generation for RSC requests\n * - Building RSC request headers (Accept, X-Timber-State-Tree)\n * - Extracting metadata from RSC response headers\n * - Fetching and decoding RSC payloads\n *\n * See design/19-client-navigation.md §\"RSC Payload Handling\"\n */\n\nimport type { SegmentInfo } from './segment-cache';\nimport type { RouterDeps } from './router';\n\n// ─── Types ───────────────────────────────────────────────────────\n\n/** Result of fetching an RSC payload — includes segment metadata. */\nexport interface FetchResult {\n  payload: unknown;\n  /**\n   * Promise that settles when the RSC decode completes or fails.\n   * The payload thenable is NOT awaited before returning (for streaming),\n   * so callers must monitor this to catch async decode errors\n   * (truncated streams, Flight parse failures) that would otherwise\n   * become unhandled rejections.\n   */\n  decodePromise: Promise<void> | null;\n  /** Segment metadata from X-Timber-Segments header for populating the segment cache. */\n  segmentInfo: SegmentInfo[] | null;\n  /** Route params from X-Timber-Params header for populating useSegmentParams(). */\n  params: Record<string, string | string[]> | null;\n  /** Segment paths that were skipped by the server (for client-side merging). */\n  skippedSegments: string[] | null;\n}\n\n// ─── Constants ───────────────────────────────────────────────────\n\nexport const RSC_CONTENT_TYPE = 'text/x-component';\n\n// ─── URL Helpers ─────────────────────────────────────────────────\n\n/**\n * Generate a short random cache-busting ID (5 chars, a-z0-9).\n * Matches the format Next.js uses for _rsc params.\n */\nfunction generateCacheBustId(): string {\n  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';\n  let id = '';\n  for (let i = 0; i < 5; i++) {\n    id += chars[(Math.random() * 36) | 0];\n  }\n  return id;\n}\n\n/**\n * Append a `_rsc=<id>` query parameter to the URL.\n * Follows Next.js's pattern — prevents CDN/browser from serving cached HTML\n * for RSC navigation requests and signals that this is an RSC fetch.\n *\n * Strips any #fragment before appending — fragments are client-only and\n * fetch() discards them, so _rsc would land inside the hash and be lost.\n */\nfunction appendRscParam(url: string): string {\n  const hashIndex = url.indexOf('#');\n  const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);\n  const separator = urlWithoutHash.includes('?') ? '&' : '?';\n  return `${urlWithoutHash}${separator}_rsc=${generateCacheBustId()}`;\n}\n\n// ─── Deployment ID ───────────────────────────────────────────────\n\n/**\n * The client's deployment ID, set at bootstrap from the runtime config.\n * Sent with every RSC/action request for version skew detection.\n * Null in dev mode. See TIM-446.\n */\nlet clientDeploymentId: string | null = null;\n\n/** Set the client deployment ID. Called once at bootstrap. */\nexport function setClientDeploymentId(id: string | null): void {\n  clientDeploymentId = id;\n}\n\n/** Get the client deployment ID. */\nexport function getClientDeploymentId(): string | null {\n  return clientDeploymentId;\n}\n\n// ─── Reload Signal ───────────────────────────────────────────────\n\n/** Header name used by the server to signal a version skew reload. */\nexport const RELOAD_HEADER = 'X-Timber-Reload';\n\n/** Header name for the client's deployment ID. */\nexport const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';\n\n/**\n * Check if a response signals a version skew reload.\n * Triggers a full page reload if the server indicates the client is stale.\n */\nexport function checkReloadSignal(response: Response): boolean {\n  return response.headers.get(RELOAD_HEADER) === '1';\n}\n\n// ─── Header Builder ──────────────────────────────────────────────\n\nexport function buildRscHeaders(\n  stateTree: { segments: string[] } | undefined,\n  currentUrl?: string\n): Record<string, string> {\n  const headers: Record<string, string> = {\n    Accept: RSC_CONTENT_TYPE,\n  };\n  if (stateTree) {\n    headers['X-Timber-State-Tree'] = JSON.stringify(stateTree);\n  }\n  // Send current URL for intercepting route resolution.\n  // The server uses this to determine if an intercepting route should\n  // render instead of the actual target route (modal pattern).\n  // See design/07-routing.md §\"Intercepting Routes\"\n  if (currentUrl) {\n    headers['X-Timber-URL'] = currentUrl;\n  }\n  // Send deployment ID for version skew detection (TIM-446).\n  // The server compares this against the current build's ID.\n  // On mismatch, the server signals a reload instead of returning\n  // an RSC payload with mismatched module references.\n  if (clientDeploymentId) {\n    headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;\n  }\n  return headers;\n}\n\n// ─── Response Header Extraction ──────────────────────────────────\n\n/** Dev-only warning for malformed framework headers. Tree-shaken in production. */\nfunction warnMalformedHeader(headerName: string, raw: string): void {\n  if (process.env.NODE_ENV !== 'production') {\n    const preview = raw.length > 200 ? raw.slice(0, 200) + '…' : raw;\n    console.warn(\n      `[timber] Malformed ${headerName} header \\u2014 JSON.parse failed. ` +\n        `This indicates a framework bug or header corruption. Raw (first 200 chars): ${preview}`\n    );\n  }\n}\n\n/**\n * Extract segment metadata from the X-Timber-Segments response header.\n * Returns null if the header is missing or malformed.\n *\n * Format: JSON array of {path, isAsync} objects describing the rendered\n * segment chain from root to leaf. Used to populate the client-side\n * segment cache for state tree diffing on subsequent navigations.\n */\nexport function extractSegmentInfo(response: Response): SegmentInfo[] | null {\n  const header = response.headers.get('X-Timber-Segments');\n  if (!header) return null;\n  try {\n    return JSON.parse(header);\n  } catch {\n    warnMalformedHeader('X-Timber-Segments', header);\n    return null;\n  }\n}\n\n/**\n * Extract skipped segment paths from the X-Timber-Skipped-Segments header.\n * Returns null if the header is missing or malformed.\n *\n * When the server skips sync layouts the client already has cached,\n * it sends this header listing the skipped segment paths (outermost first).\n * The client uses this to merge the partial payload with cached segments.\n */\nexport function extractSkippedSegments(response: Response): string[] | null {\n  const header = response.headers.get('X-Timber-Skipped-Segments');\n  if (!header) return null;\n  try {\n    const parsed = JSON.parse(header);\n    return Array.isArray(parsed) ? parsed : null;\n  } catch {\n    warnMalformedHeader('X-Timber-Skipped-Segments', header);\n    return null;\n  }\n}\n\n/**\n * Extract route params from the X-Timber-Params response header.\n * Returns null if the header is missing or malformed.\n *\n * Used to populate useSegmentParams() after client-side navigation.\n */\nexport function extractParams(response: Response): Record<string, string | string[]> | null {\n  const header = response.headers.get('X-Timber-Params');\n  if (!header) return null;\n  try {\n    return JSON.parse(header);\n  } catch {\n    warnMalformedHeader('X-Timber-Params', header);\n    return null;\n  }\n}\n\n// ─── Redirect Error ──────────────────────────────────────────────\n\n/**\n * Thrown when an RSC payload response contains X-Timber-Redirect header.\n * Caught in navigate() to trigger a soft router navigation to the redirect target.\n */\nexport class RedirectError extends Error {\n  readonly redirectUrl: string;\n  constructor(url: string) {\n    super(`Server redirect to ${url}`);\n    this.redirectUrl = url;\n  }\n}\n\n/**\n * Thrown when the server signals a version skew (X-Timber-Reload header).\n * Caught in navigate() to trigger a full page reload.\n * See TIM-446.\n */\nexport class VersionSkewError extends Error {\n  constructor() {\n    super('Version skew detected — server has been redeployed');\n  }\n}\n\n/**\n * Thrown when the server returns an error for an RSC payload request.\n * The server sends X-Timber-Error header and a JSON body instead of a\n * broken RSC stream for any RenderError (4xx or 5xx). Caught in\n * navigate() to trigger a hard navigation so the server can render\n * the error page as HTML.\n *\n * See design/10-error-handling.md §\"Error Page Rendering for Client Navigation\"\n */\nexport class ServerErrorResponse extends Error {\n  readonly status: number;\n  readonly url: string;\n  constructor(status: number, url: string) {\n    super(`Server error ${status} during navigation to ${url}`);\n    this.status = status;\n    this.url = url;\n  }\n}\n\n// ─── Stream Completion Tracking ───────────────────────────────────\n\n/**\n * Wrap a response body stream to track when it's fully consumed.\n * Returns a new body that passes all chunks through unchanged, plus\n * a `done` promise that resolves when the last chunk is read (or\n * rejects if the stream errors).\n *\n * Used to keep React transitions open for the full RSC stream\n * duration — createFromFetch's thenable resolves on shell arrival,\n * but we need stream completion for useOptimistic pending state.\n */\nfunction trackStreamCompletion(body: ReadableStream<Uint8Array>): {\n  body: ReadableStream<Uint8Array>;\n  done: Promise<void>;\n} {\n  let resolveDone!: () => void;\n  let rejectDone!: (e: unknown) => void;\n  const done = new Promise<void>((res, rej) => {\n    resolveDone = res;\n    rejectDone = rej;\n  });\n\n  const reader = body.getReader();\n  const tracked = new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        const result = await reader.read();\n        if (result.done) {\n          controller.close();\n          resolveDone();\n        } else {\n          controller.enqueue(result.value);\n        }\n      } catch (error) {\n        controller.error(error);\n        rejectDone(error);\n      }\n    },\n    cancel(reason) {\n      reader.cancel(reason);\n      resolveDone();\n    },\n  });\n\n  return { body: tracked, done };\n}\n\n// ─── Fetch ───────────────────────────────────────────────────────\n\n/**\n * Fetch an RSC payload from the server. If a decodeRsc function is provided,\n * the response is decoded into a React element tree via createFromFetch.\n * Otherwise, the raw response text is returned (test mode).\n */\nexport async function fetchRscPayload(\n  url: string,\n  deps: RouterDeps,\n  stateTree?: { segments: string[] },\n  currentUrl?: string,\n  signal?: AbortSignal\n): Promise<FetchResult> {\n  const rscUrl = appendRscParam(url);\n  const headers = buildRscHeaders(stateTree, currentUrl);\n  if (deps.decodeRsc) {\n    // Production path: use createFromFetch for streaming RSC decoding.\n    // createFromFetch takes a Promise<Response> and progressively parses\n    // the RSC Flight stream as chunks arrive.\n    //\n    // Intercept the response to read segment metadata before createFromFetch\n    // consumes the body. Reading headers does NOT consume the body stream.\n    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });\n    let segmentInfo: SegmentInfo[] | null = null;\n    let params: Record<string, string | string[]> | null = null;\n    let skippedSegments: string[] | null = null;\n    // Track when the full RSC body stream is consumed (not just shell).\n    // Initialized to resolved for bodyless responses; overwritten when\n    // the response has a body.\n    let streamDone: Promise<void> = Promise.resolve();\n\n    const wrappedPromise = fetchPromise.then((response) => {\n      // Version skew detection (TIM-446): if the server signals a reload,\n      // throw VersionSkewError so the caller (router navigate) can trigger\n      // a full page reload.\n      if (checkReloadSignal(response)) {\n        throw new VersionSkewError();\n      }\n      // Detect server-side redirects. The server returns 204 + X-Timber-Redirect\n      // for RSC payload requests instead of a raw 302, because fetch with\n      // redirect: \"manual\" turns 302s into opaque redirects (status 0, null body)\n      // which crashes createFromFetch when it tries to read the body stream.\n      const redirectLocation =\n        response.headers.get('X-Timber-Redirect') ||\n        (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);\n      if (redirectLocation) {\n        throw new RedirectError(redirectLocation);\n      }\n      // Detect server error responses. The server returns X-Timber-Error header\n      // with a JSON body instead of a broken RSC stream for any RenderError\n      // (4xx or 5xx). Hard-navigate so the server renders the error page as HTML.\n      // See design/10-error-handling.md §\"Error Page Rendering for Client Navigation\"\n      if (response.headers.get('X-Timber-Error') === '1') {\n        throw new ServerErrorResponse(response.status, url);\n      }\n      // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload\n      // as React elements — React 19 Float handles them. See TIM-1151.\n      segmentInfo = extractSegmentInfo(response);\n      params = extractParams(response);\n      skippedSegments = extractSkippedSegments(response);\n\n      // Wrap the body to track full stream consumption. createFromFetch's\n      // thenable resolves when the root model (shell) arrives, but we need\n      // to know when ALL chunks are read so the React transition stays\n      // open for the full streaming duration (keeps useOptimistic alive).\n      if (response.body) {\n        const tracked = trackStreamCompletion(response.body);\n        streamDone = tracked.done;\n        streamDone.catch(() => {}); // prevent unhandled rejection\n        return new Response(tracked.body, {\n          headers: response.headers,\n          status: response.status,\n        });\n      }\n      return response;\n    });\n    // Await headers so segmentInfo/params are populated.\n    await wrappedPromise;\n    // Start decoding but do NOT await — return the in-progress thenable.\n    // React can render a Flight thenable directly: it suspends on unresolved\n    // parts and progressively renders as chunks arrive, spreading work across\n    // frames instead of blocking the main thread in one burst.\n    const payload = deps.decodeRsc(wrappedPromise);\n    // Combine stream completion with payload error propagation.\n    // streamDone keeps the transition open for the full RSC stream\n    // duration (useOptimistic pending state). payloadError propagates\n    // decode failures (stale client references, Flight parse errors)\n    // so the router's catch block can trigger recovery (stale reload).\n    const payloadError = new Promise<void>((_, reject) => {\n      Promise.resolve(payload).then(() => {}, reject);\n    });\n    payloadError.catch(() => {});\n    const decodePromise = Promise.race([streamDone, payloadError]);\n    return {\n      payload,\n      decodePromise,\n      segmentInfo,\n      params,\n      skippedSegments,\n    };\n  }\n  // Test/fallback path: return raw text\n  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });\n  // Check for redirect in test path too\n  if (response.status >= 300 && response.status < 400) {\n    const location = response.headers.get('Location');\n    if (location) {\n      throw new RedirectError(location);\n    }\n  }\n  return {\n    payload: await response.text(),\n    decodePromise: null,\n    segmentInfo: extractSegmentInfo(response),\n    params: extractParams(response),\n    skippedSegments: extractSkippedSegments(response),\n  };\n}\n","// Segment Router — manages client-side navigation and RSC payload fetching\n// See design/19-client-navigation.md for the full architecture.\n\nimport { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';\nimport type { SegmentInfo } from './segment-cache';\nimport { HistoryStack } from './history';\nimport { setCurrentParams } from './use-segment-params.js';\nimport {\n  setNavigationState,\n  getNavigationState,\n  type NavigationState,\n} from './navigation-context.js';\n\nimport {\n  fetchRscPayload,\n  RedirectError,\n  ServerErrorResponse,\n  VersionSkewError,\n} from './rsc-fetch.js';\nimport { setHardNavigating, supersedeNavigationTransitions } from './navigation-root.js';\nimport type { FetchResult } from './rsc-fetch.js';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface NavigationOptions {\n  /** Set to false to prevent scroll-to-top on forward navigation */\n  scroll?: boolean;\n  /** Use replaceState instead of pushState (replaces current history entry) */\n  replace?: boolean;\n  /**\n   * @internal AbortSignal from the Navigation API's NavigateEvent.\n   * When provided, the signal is linked to the router's per-navigation\n   * AbortController so in-flight RSC fetches are cancelled when a new\n   * navigation starts.\n   */\n  _signal?: AbortSignal;\n  /**\n   * @internal Skip pushState/replaceState — the Navigation API has already\n   * updated the URL via event.intercept(). Used for external navigations\n   * intercepted by the navigate event handler.\n   */\n  _skipHistory?: boolean;\n}\n\n/**\n * Function that decodes an RSC Flight stream into a React element tree.\n * In production: createFromFetch from @vitejs/plugin-rsc/browser.\n * In tests: a mock that returns the raw payload.\n */\nexport type RscDecoder = (fetchPromise: Promise<Response>) => unknown;\n\n/**\n * Function that renders a decoded RSC element tree into the DOM.\n * In production: reactRoot.render(element).\n * In tests: a no-op or mock.\n *\n * Receives the current NavigationState explicitly — no temporal\n * coupling with setNavigationState/getNavigationState. The renderer\n * wraps the element in NavigationProvider with this state.\n */\nexport type RootRenderer = (element: unknown, navState: NavigationState) => void;\n\n/**\n * Platform dependencies injected for testability. In production these\n * map to browser APIs; in tests they're replaced with mocks.\n */\nexport interface RouterDeps {\n  fetch: (url: string, init: RequestInit) => Promise<Response>;\n  pushState: (data: unknown, unused: string, url: string) => void;\n  replaceState: (data: unknown, unused: string, url: string) => void;\n  scrollTo: (x: number, y: number) => void;\n  getCurrentUrl: () => string;\n  getScrollY: () => number;\n  /** Decode RSC Flight stream into React elements. If not provided, raw response text is stored. */\n  decodeRsc?: RscDecoder;\n  /** Render decoded RSC tree into the DOM. If not provided, rendering is a no-op. */\n  renderRoot?: RootRenderer;\n  /**\n   * Schedule a callback after the next paint. In the browser, this is\n   * requestAnimationFrame + setTimeout(0) to run after React commits.\n   * In tests, this runs the callback synchronously.\n   */\n  afterPaint?: (callback: () => void) => void;\n  /**\n   * Run a navigation inside a React transition with optimistic pending URL.\n   * The pending URL shows immediately (useOptimistic urgent update) and\n   * reverts when the transition commits (atomic with the new tree).\n   *\n   * The `perform` callback receives a `wrapPayload` function to wrap the\n   * decoded RSC payload with NavigationProvider + NuqsAdapter before\n   * NavigationRoot sets it as the new element. The `wrapPayload` function\n   * receives the NavigationState explicitly — no temporal coupling with\n   * getNavigationState().\n   *\n   * If not provided (tests), the router falls back to renderRoot.\n   */\n  navigateTransition?: (\n    pendingUrl: string,\n    perform: (\n      wrapPayload: (\n        payload: unknown,\n        navState: NavigationState,\n        segmentUpdates?: Map<string, unknown>\n      ) => unknown\n    ) => Promise<{ element: unknown; decodePromise: Promise<void> | null }>\n  ) => Promise<void>;\n\n  /**\n   * Whether the Navigation API is active and handling traversals.\n   * When true, the popstate handler is a no-op — the Navigation API's\n   * navigate event covers back/forward button presses.\n   */\n  navigationApiActive?: boolean;\n\n  /**\n   * Called around pushState/replaceState to set a flag that prevents\n   * the Navigation API's navigate listener from double-handling\n   * router-initiated navigations.\n   */\n  setRouterNavigating?: (value: boolean) => void;\n\n  /**\n   * Save scroll position via the Navigation API's per-entry state.\n   * When provided, used instead of history.replaceState for scroll storage.\n   */\n  saveNavigationEntryScroll?: (scrollY: number) => void;\n\n  /**\n   * Signal that a router-initiated navigation has completed. Resolves the\n   * deferred promise that ties the browser's native loading state to the\n   * navigation lifecycle. Called in the finally block of navigate/refresh,\n   * aligned with when the TopLoader's pendingUrl clears.\n   */\n  completeRouterNavigation?: () => void;\n\n  /**\n   * Get the current unwrapped RSC payload element. Used for partial\n   * navigation: the router re-wraps the same element with new\n   * NavigationProvider context so mounted SegmentOutlets are preserved.\n   */\n  _getCurrentPayload?: () => unknown;\n\n  /**\n   * Initiate a navigation via the Navigation API (`navigation.navigate()`).\n   * Fires the navigate event BEFORE committing the URL, allowing Chrome\n   * to show its native loading indicator. Falls back to pushState when\n   * unavailable.\n   */\n  navigationNavigate?: (url: string, replace: boolean) => void;\n\n  /**\n   * Scroll the element matching a URL #fragment into view. Returns true\n   * when a matching element was found and scrolled. When absent or false,\n   * the router falls back to scroll-to-top on forward navigation — same\n   * as a full page load with an unknown fragment landing at the top.\n   */\n  scrollToHash?: (hash: string) => boolean;\n}\n\nexport interface RouterInstance {\n  /** Navigate to a new URL (forward navigation) */\n  navigate(url: string, options?: NavigationOptions): Promise<void>;\n  /** Full re-render of the current URL — no state tree sent */\n  refresh(): Promise<void>;\n  /** Handle a popstate event (back/forward button). scrollY is read from history.state. */\n  handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<void>;\n  /** Whether a navigation is currently in flight */\n  isPending(): boolean;\n  /** The URL currently being navigated to, or null if idle */\n  getPendingUrl(): string | null;\n  /** Subscribe to pending state changes */\n  onPendingChange(listener: (pending: boolean) => void): () => void;\n  /** Prefetch an RSC payload for a URL (used by Link hover) */\n  prefetch(url: string): void;\n  /**\n   * Apply a piggybacked revalidation payload from a server action response.\n   * Renders the element tree and updates head elements without a server fetch.\n   * See design/08-forms-and-actions.md §\"Single-Roundtrip Revalidation\".\n   */\n  applyRevalidation(element: unknown): void;\n  /**\n   * Populate the segment cache from server-provided segment metadata.\n   * Called on initial hydration with segment info embedded in the HTML.\n   */\n  initSegmentCache(segments: SegmentInfo[]): void;\n\n  /** The segment cache (exposed for tests and <Link> prefetch) */\n  segmentCache: SegmentCache;\n  /** The prefetch cache (exposed for tests and <Link> prefetch) */\n  prefetchCache: PrefetchCache;\n  /** The history stack (exposed for tests) */\n  historyStack: HistoryStack;\n}\n\n/**\n * Check if an error is an abort error (connection closed / fetch aborted).\n * Browsers throw DOMException with name 'AbortError' when a fetch is aborted.\n */\nfunction isAbortError(error: unknown): boolean {\n  if (error instanceof DOMException && error.name === 'AbortError') return true;\n  if (error instanceof Error && error.name === 'AbortError') return true;\n  return false;\n}\n\n// ─── Router Factory ──────────────────────────────────────────────\n\n/**\n * Create a router instance. In production, called once at app hydration\n * with real browser APIs. In tests, called with mock dependencies.\n */\n/**\n * Router navigation phase — discriminated union replacing scattered\n * `pending` + `pendingUrl` boolean flags.\n *\n * - `idle`: No navigation in flight. The committed params/pathname\n *   are current.\n * - `navigating`: A fetch or render is in progress. `targetUrl` is\n *   the destination being navigated to.\n */\nexport type RouterPhase = { phase: 'idle' } | { phase: 'navigating'; targetUrl: string };\n\nexport function createRouter(deps: RouterDeps): RouterInstance {\n  const segmentCache = new SegmentCache();\n  const prefetchCache = new PrefetchCache();\n  const historyStack = new HistoryStack();\n  let routerPhase: RouterPhase = { phase: 'idle' };\n  const pendingListeners = new Set<(pending: boolean) => void>();\n\n  // AbortController for the current in-flight navigation.\n  // When a new navigation starts, the previous controller is aborted,\n  // cancelling any in-progress RSC fetch. This provides automatic\n  // cancellation of stale fetches regardless of Navigation API support.\n  let currentNavAbort: AbortController | null = null;\n\n  /**\n   * Create a new AbortController for a navigation, superseding any\n   * previous in-flight navigation. Optionally links to an external\n   * signal (e.g., from the Navigation API's NavigateEvent.signal).\n   *\n   * Superseding is one operation with three parts:\n   * 1. Abort the previous navigation's fetch.\n   * 2. Invalidate its render transition so a response that already\n   *    arrived can't commit a stale tree (NavigationRoot's transId guard).\n   * 3. Resolve its Navigation API deferred — the superseded navigation's\n   *    finally block is staleness-guarded (see TIM-1034) and no longer\n   *    cleans up after itself, so the browser's native loading state for\n   *    the dead navigation is cleared here.\n   */\n  function createNavAbort(externalSignal?: AbortSignal): AbortController {\n    if (currentNavAbort) {\n      currentNavAbort.abort();\n      supersedeNavigationTransitions();\n      deps.completeRouterNavigation?.();\n    }\n    const controller = new AbortController();\n    currentNavAbort = controller;\n\n    // If an external signal is provided (e.g., Navigation API),\n    // forward its abort to our controller.\n    if (externalSignal) {\n      if (externalSignal.aborted) {\n        controller.abort();\n      } else {\n        externalSignal.addEventListener('abort', () => controller.abort(), { once: true });\n      }\n    }\n\n    return controller;\n  }\n\n  function setPending(value: boolean, url?: string): void {\n    const next: RouterPhase =\n      value && url ? { phase: 'navigating', targetUrl: url } : { phase: 'idle' };\n    // Skip no-op updates\n    if (\n      routerPhase.phase === next.phase &&\n      (routerPhase.phase === 'idle' ||\n        (routerPhase.phase === 'navigating' &&\n          next.phase === 'navigating' &&\n          routerPhase.targetUrl === next.targetUrl))\n    ) {\n      return;\n    }\n    routerPhase = next;\n    // Notify external store listeners (non-React consumers).\n    // React-facing pending state is handled by useOptimistic in\n    // NavigationRoot via navigateTransition — not this function.\n    for (const listener of pendingListeners) {\n      listener(value);\n    }\n  }\n\n  /** Update the segment cache from server-provided segment metadata. */\n  function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {\n    if (!segmentInfo || segmentInfo.length === 0) return;\n    const tree = buildSegmentTree(segmentInfo);\n    if (tree) {\n      segmentCache.set('/', tree);\n    }\n  }\n\n  /** Render a decoded RSC payload into the DOM if a renderer is available. */\n  function renderPayload(payload: unknown, navState: NavigationState): void {\n    if (deps.renderRoot) {\n      deps.renderRoot(payload, navState);\n    }\n  }\n\n  function isPartialNavigation(skippedSegments: string[] | null | undefined): boolean {\n    return skippedSegments != null && skippedSegments.length > 0;\n  }\n\n  /**\n   * Build a segment updates map for partial navigation. Identifies the\n   * first non-skipped segment and maps it to the payload content.\n   */\n  function buildSegmentUpdates(result: FetchResult): Map<string, unknown> {\n    const skipped = new Set(result.skippedSegments!);\n    const segmentInfo = result.segmentInfo;\n    const updates = new Map<string, unknown>();\n    if (segmentInfo) {\n      for (const info of segmentInfo) {\n        if (!skipped.has(info.segmentId ?? info.path)) {\n          // Use segmentId (outlet key) when available — route groups\n          // use a disambiguated key like \"/(marketing)\" instead of \"/\".\n          updates.set(info.segmentId ?? info.path, result.payload);\n          break;\n        }\n      }\n    }\n    return updates;\n  }\n\n  /**\n   * Update navigation state (params + pathname) for the next render.\n   *\n   * Sets the module-level fallback (for tests and SSR) and the\n   * globalThis bridge, then returns the NavigationState so callers\n   * can pass it explicitly to renderRoot/wrapPayload — eliminating\n   * temporal coupling with getNavigationState().\n   */\n  function updateNavigationState(\n    params: Record<string, string | string[]> | null | undefined,\n    url: string\n  ): NavigationState {\n    const resolvedParams = params ?? {};\n    // Module-level fallback for tests (no NavigationProvider) and SSR\n    setCurrentParams(resolvedParams);\n    // globalThis bridge — kept for backward compat\n    const parsed = new URL(url, 'http://localhost');\n    const pathname = parsed.pathname || '/';\n    const search = parsed.search;\n    const navState: NavigationState = { params: resolvedParams, pathname, search };\n    setNavigationState(navState);\n    return navState;\n  }\n\n  /**\n   * Render a payload via navigateTransition (production) or renderRoot (tests).\n   * The perform callback should fetch data, update state, and return the\n   * FetchResult plus the NavigationState (so it can be passed explicitly\n   * to wrapPayload/renderRoot without temporal coupling).\n   */\n  async function renderViaTransition(\n    url: string,\n    perform: () => Promise<FetchResult & { navState: NavigationState }>\n  ): Promise<void> {\n    if (deps.navigateTransition) {\n      await deps.navigateTransition(url, async (wrapPayload) => {\n        const result = await perform();\n\n        if (isPartialNavigation(result.skippedSegments)) {\n          const segmentUpdates = buildSegmentUpdates(result);\n\n          historyStack.push(url, {\n            payload: null,\n            params: result.params,\n          });\n\n          // Re-wrap the CURRENT element with new context values.\n          // SegmentOutlets read updates from SegmentUpdateContext;\n          // NavigationProvider gets new params/pathname.\n          const element = wrapPayload(\n            deps._getCurrentPayload?.() ?? result.payload,\n            result.navState,\n            segmentUpdates\n          );\n          return { element, decodePromise: result.decodePromise };\n        }\n\n        // Full navigation — empty updates, render the new tree.\n        historyStack.push(url, {\n          payload: result.payload,\n          params: result.params,\n        });\n        const element = wrapPayload(result.payload, result.navState);\n        return { element, decodePromise: result.decodePromise };\n      });\n      return;\n    }\n    // Fallback: no transition (tests, no React tree)\n    const result = await perform();\n    if (isPartialNavigation(result.skippedSegments)) {\n      historyStack.push(url, {\n        payload: null,\n        params: result.params,\n      });\n    } else {\n      // Resolve thenables before storing/rendering in the fallback path\n      // (tests without navigateTransition). In production, React handles\n      // thenables via Suspense; in tests, renderRoot expects resolved values.\n      const payload =\n        result.payload != null && typeof result.payload === 'object' && 'then' in result.payload\n          ? await (result.payload as PromiseLike<unknown>)\n          : result.payload;\n      historyStack.push(url, {\n        payload,\n        params: result.params,\n      });\n      renderPayload(payload, result.navState);\n    }\n  }\n\n  /** Run a callback after the next paint (after React commit). */\n  function afterPaint(callback: () => void): void {\n    if (deps.afterPaint) {\n      deps.afterPaint(callback);\n    } else {\n      callback();\n    }\n  }\n\n  /**\n   * Schedule scroll restoration after the next paint and fire the\n   * scroll-restored event. Used by navigate, popstate, and refresh.\n   */\n  function restoreScrollAfterPaint(scrollY: number): void {\n    afterPaint(() => {\n      deps.scrollTo(0, scrollY);\n      window.dispatchEvent(new Event('timber:scroll-restored'));\n    });\n  }\n\n  /**\n   * Scroll to the element matching the URL #fragment after paint, falling\n   * back to scroll-to-top when no element matches (matching full-page-load\n   * behavior for an unknown fragment). Used by forward navigation to a\n   * hash-bearing URL (TIM-1035).\n   */\n  function scrollToHashAfterPaint(hash: string): void {\n    afterPaint(() => {\n      if (deps.scrollToHash?.(hash) !== true) {\n        deps.scrollTo(0, 0);\n      }\n      window.dispatchEvent(new Event('timber:scroll-restored'));\n    });\n  }\n\n  /**\n   * Core navigation logic shared between the transition and fallback paths.\n   * Fetches the RSC payload, updates all state, and returns the result.\n   */\n  async function performNavigationFetch(\n    url: string,\n    options: { replace: boolean; commitUrl?: string; signal?: AbortSignal; skipHistory?: boolean }\n  ): Promise<FetchResult & { navState: NavigationState }> {\n    // Check prefetch cache first. PrefetchResult has optional segmentInfo/params\n    // fields — normalize to null for FetchResult compatibility.\n    const prefetched = prefetchCache.consume(url);\n    let result: FetchResult | undefined = prefetched\n      ? {\n          payload: prefetched.payload,\n          decodePromise: null,\n          segmentInfo: prefetched.segmentInfo ?? null,\n          params: prefetched.params ?? null,\n          skippedSegments: prefetched.skippedSegments ?? null,\n        }\n      : undefined;\n\n    if (result === undefined) {\n      // Fetch RSC payload with state tree for partial rendering.\n      // Send current URL for intercepting route resolution (modal pattern).\n      const stateTree = segmentCache.serializeStateTree();\n      const rawCurrentUrl = deps.getCurrentUrl();\n      const currentUrl = rawCurrentUrl.startsWith('http')\n        ? new URL(rawCurrentUrl).pathname\n        : new URL(rawCurrentUrl, 'http://localhost').pathname;\n      result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);\n    }\n\n    // Update the browser history — skip when the Navigation API has already\n    // updated the URL via event.intercept() (external navigations).\n    // The committed URL keeps the #fragment (commitUrl) even though the\n    // fetch/history-stack URL is hash-less (TIM-1035).\n    if (!options.skipHistory) {\n      const commitUrl = options.commitUrl ?? url;\n      // Set the router-navigating flag so the Navigation API's navigate\n      // listener doesn't double-intercept this pushState/replaceState.\n      deps.setRouterNavigating?.(true);\n      if (options.replace) {\n        deps.replaceState({ timber: true, scrollY: 0 }, '', commitUrl);\n      } else {\n        deps.pushState({ timber: true, scrollY: 0 }, '', commitUrl);\n      }\n      deps.setRouterNavigating?.(false);\n    }\n\n    // NOTE: History push is deferred — the merged payload (after segment\n    // merging in renderViaTransition) is stored by the caller, not here.\n    // Storing result.payload here would record the partial (pre-merge)\n    // RSC tree, causing handlePopState to replay an incomplete tree.\n\n    // Update the segment cache with the new route's segment tree.\n    updateSegmentCache(result.segmentInfo);\n\n    // Update navigation state and capture it for explicit passing.\n    const navState = updateNavigationState(result.params, url);\n\n    return { ...result, navState };\n  }\n\n  async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {\n    const scroll = options.scroll !== false;\n    const replace = options.replace === true;\n    const externalSignal = options._signal as AbortSignal | undefined;\n    const skipHistory = options._skipHistory === true;\n\n    // Split the #fragment off the navigation URL (TIM-1035). The full URL\n    // (with hash) is committed to the address bar; the hash-less URL is used\n    // for the RSC fetch (fragments are client-only — keeping it would also\n    // swallow the ?_rsc cache-bust param into the fragment) and for\n    // history-stack/prefetch keys (popstate lookups use pathname + search).\n    const hashIndex = url.indexOf('#');\n    const hash = hashIndex === -1 ? '' : url.slice(hashIndex);\n    const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);\n\n    // Create an abort controller for this navigation. Links to the external\n    // signal (Navigation API's event.signal) when provided.\n    const navAbort = createNavAbort(externalSignal);\n\n    // Capture the departing page's scroll position for scroll={false} preservation.\n    const currentScrollY = deps.getScrollY();\n\n    // Save the departing page's scroll position — use Navigation API entry\n    // state when available, otherwise fall back to history.state.\n    if (deps.saveNavigationEntryScroll) {\n      deps.saveNavigationEntryScroll(currentScrollY);\n    } else {\n      deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());\n    }\n\n    // When Navigation API is active, initiate the navigation via\n    // navigation.navigate() BEFORE the fetch. Unlike history.pushState()\n    // which commits the URL synchronously (so Chrome sees it as \"done\"),\n    // navigation.navigate() fires the navigate event before committing.\n    // Our handler intercepts with a deferred promise, and Chrome shows\n    // its native loading indicator until completeRouterNavigation()\n    // resolves it in the finally block (same time as TopLoader clears).\n    let effectiveSkipHistory = skipHistory;\n    if (!skipHistory && deps.navigationNavigate) {\n      deps.setRouterNavigating?.(true);\n      deps.navigationNavigate(url, replace);\n      deps.setRouterNavigating?.(false);\n      effectiveSkipHistory = true;\n    }\n\n    setPending(true, url);\n\n    try {\n      await renderViaTransition(fetchUrl, () =>\n        performNavigationFetch(fetchUrl, {\n          replace,\n          commitUrl: url,\n          signal: navAbort.signal,\n          skipHistory: effectiveSkipHistory,\n        })\n      );\n\n      // Notify nuqs adapter (and any other listeners) that navigation completed.\n      window.dispatchEvent(new Event('timber:navigation-end'));\n\n      // Scroll-to-top on forward navigation, scroll to the #fragment target\n      // when the URL has one, or restore captured position for scroll={false}.\n      // React's render() on the document root can reset scroll during DOM\n      // reconciliation, so all scroll must be actively managed.\n      if (scroll && hash) {\n        scrollToHashAfterPaint(hash);\n      } else {\n        restoreScrollAfterPaint(scroll ? 0 : currentScrollY);\n      }\n    } catch (error) {\n      // Version skew — server has been redeployed. Full page reload\n      // so the browser fetches the new bundle. See TIM-446.\n      if (error instanceof VersionSkewError) {\n        setHardNavigating(true);\n        window.location.reload();\n        return new Promise(() => {}) as never;\n      }\n      // Server-side redirect during RSC fetch → soft router navigation.\n      // The redirect navigate will push/replace its own URL.\n      if (error instanceof RedirectError) {\n        // Drop the redirect if a newer navigation superseded this one\n        // while the redirect response was in flight — the newer\n        // navigation wins, same as the stale-transition guard.\n        if (currentNavAbort !== navAbort) return;\n        // The recursive navigate() supersedes this one via createNavAbort,\n        // which also resolves this navigation's Navigation API deferred.\n        await navigate(error.redirectUrl, { replace: true });\n        return;\n      }\n      // Server 5xx error — hard-navigate so the server renders the\n      // error page as HTML. See design/10-error-handling.md\n      // §\"Error Page Rendering for Client Navigation\".\n      //\n      // Set hard-navigating flag BEFORE setting window.location.href:\n      // 1. Prevents Navigation API from intercepting → infinite loop\n      // 2. Causes NavigationRoot to throw unresolvedThenable → prevents\n      //    React from rendering children during page teardown (avoids\n      //    \"Rendered more hooks\" crashes). See TIM-626.\n      if (error instanceof ServerErrorResponse) {\n        setHardNavigating(true);\n        window.location.href = error.url;\n        return new Promise(() => {}) as never;\n      }\n      // Abort errors are not application errors — swallow silently.\n      if (isAbortError(error)) return;\n      throw error;\n    } finally {\n      // Staleness guard (TIM-1034): only clean up when this navigation\n      // still owns the abort controller. When a newer navigation\n      // superseded this one, createNavAbort() already replaced\n      // currentNavAbort — running setPending(false) /\n      // completeRouterNavigation() here would clear the NEWER\n      // navigation's pending state and resolve its Navigation API\n      // deferred. The superseding navigation resolved OUR deferred in\n      // createNavAbort().\n      if (currentNavAbort === navAbort) {\n        // Clear the abort controller so we don't abort a completed\n        // navigation when the next one starts. In dev mode, the RSC body\n        // stream stays open after data arrives (React's Flight client\n        // waits for debug rows). Aborting a \"completed\" navigation kills\n        // the open stream reader → \"BodyStreamBuffer was aborted\".\n        currentNavAbort = null;\n        setPending(false);\n        // Resolve the Navigation API deferred — clears the browser's\n        // native loading state (tab spinner) at the same time as the\n        // TopLoader.\n        deps.completeRouterNavigation?.();\n      }\n    }\n  }\n\n  async function refresh(): Promise<void> {\n    const currentUrl = deps.getCurrentUrl();\n    const navAbort = createNavAbort();\n\n    setPending(true, currentUrl);\n\n    try {\n      await renderViaTransition(currentUrl, async () => {\n        // No state tree sent — server renders the complete RSC payload\n        const result = await fetchRscPayload(\n          currentUrl,\n          deps,\n          undefined,\n          undefined,\n          navAbort.signal\n        );\n        // History push handled by renderViaTransition (stores merged payload)\n        updateSegmentCache(result.segmentInfo);\n        const navState = updateNavigationState(result.params, currentUrl);\n        return { ...result, navState };\n      });\n    } catch (error) {\n      if (isAbortError(error)) return;\n      throw error;\n    } finally {\n      // Staleness guard (TIM-1034) — see navigate()'s finally block.\n      if (currentNavAbort === navAbort) {\n        currentNavAbort = null;\n        setPending(false);\n        deps.completeRouterNavigation?.();\n      }\n    }\n  }\n\n  async function handlePopState(\n    url: string,\n    scrollY: number = 0,\n    externalSignal?: AbortSignal\n  ): Promise<void> {\n    // Scroll position is read from history.state by the caller (browser-entry.ts)\n    // and passed in. This is more reliable than tracking scroll per-URL in memory\n    // because the browser maintains per-entry state even with duplicate URLs.\n    const entry = historyStack.get(url);\n\n    if (entry && entry.payload !== null) {\n      // Replay cached payload — no server roundtrip.\n      //\n      // A forward navigation may still be in flight (back pressed while a\n      // slow RSC fetch was pending). createNavAbort() supersedes it: aborts\n      // its fetch and invalidates its render transition so the stale\n      // forward payload can't commit over this replay (TIM-1022). The\n      // replay itself is synchronous — nothing to abort later — so the\n      // controller is cleared immediately, and any pending state left by\n      // the superseded navigation is reset.\n      createNavAbort(externalSignal);\n      currentNavAbort = null;\n      setPending(false);\n      const navState = updateNavigationState(entry.params, url);\n      renderPayload(entry.payload, navState);\n      restoreScrollAfterPaint(scrollY);\n    } else {\n      // No cached payload — fetch from server.\n      // This happens when navigating back to the initial SSR'd page\n      // (its payload is null since it was rendered via SSR, not RSC fetch)\n      // or when the entry doesn't exist at all.\n      const navAbort = createNavAbort(externalSignal);\n      setPending(true, url);\n      try {\n        await renderViaTransition(url, async () => {\n          const stateTree = segmentCache.serializeStateTree();\n          const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);\n          updateSegmentCache(result.segmentInfo);\n          const navState = updateNavigationState(result.params, url);\n          // History push handled by renderViaTransition (stores merged payload)\n          return { ...result, navState };\n        });\n\n        restoreScrollAfterPaint(scrollY);\n      } catch (error) {\n        if (isAbortError(error)) return;\n        throw error;\n      } finally {\n        // Staleness guard (TIM-1034) — see navigate()'s finally block.\n        if (currentNavAbort === navAbort) {\n          currentNavAbort = null;\n          setPending(false);\n        }\n      }\n    }\n  }\n\n  /**\n   * Prefetch an RSC payload for a URL and store it in the prefetch cache.\n   * Called on hover of <Link prefetch> elements.\n   */\n  function prefetch(url: string): void {\n    // Strip fragment — it's client-only and would swallow the _rsc cache-bust\n    // param into the hash. The hash-less key also matches navigate()'s fetchUrl.\n    const hashIndex = url.indexOf('#');\n    const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);\n\n    // Don't prefetch if already cached\n    if (prefetchCache.get(fetchUrl) !== undefined) return;\n    if (historyStack.has(fetchUrl)) return;\n\n    // Fire-and-forget fetch\n    const stateTree = segmentCache.serializeStateTree();\n    void fetchRscPayload(fetchUrl, deps, stateTree).then(\n      (result) => {\n        result.decodePromise?.catch(() => {});\n        prefetchCache.set(fetchUrl, result);\n      },\n      () => {\n        // Prefetch failure is non-fatal — navigation will fetch fresh\n      }\n    );\n  }\n\n  return {\n    navigate,\n    refresh,\n    handlePopState,\n    isPending: () => routerPhase.phase === 'navigating',\n    getPendingUrl: () => (routerPhase.phase === 'navigating' ? routerPhase.targetUrl : null),\n    onPendingChange(listener) {\n      pendingListeners.add(listener);\n      return () => pendingListeners.delete(listener);\n    },\n    prefetch,\n    applyRevalidation(element: unknown): void {\n      // Render the piggybacked element tree from a server action response.\n      // Updates the current history entry with the fresh payload —\n      // same as refresh() but without a server fetch.\n      // Revalidation payloads are already resolved (no Flight thenable),\n      // so no segment merging is needed — just cache and render.\n      const currentUrl = deps.getCurrentUrl();\n\n      // Revalidation doesn't change params/pathname — preserve current state.\n      // DO NOT call updateNavigationState(null, ...) here: that normalizes\n      // params to {}, clearing dynamic route params on every action response.\n      const navState = getNavigationState();\n\n      // Keep params on the overwritten entry — dropping them would make\n      // away-and-back navigation replay this page with params normalized\n      // to {} (TIM-1037).\n      historyStack.push(currentUrl, {\n        payload: element,\n        params: navState.params,\n      });\n      renderPayload(element, navState);\n    },\n    initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),\n    segmentCache,\n    prefetchCache,\n    historyStack,\n  };\n}\n","/**\n * useSearchParams() — client-side hook for reading URL search params.\n *\n * Returns a read-only URLSearchParams instance reflecting the current\n * URL's query string. Updates when client-side navigation changes the URL.\n *\n * On the client, reads from NavigationContext which is updated atomically\n * with the RSC tree render during full navigations, AND by\n * syncShallowSearch() for shallow URL updates (nuqs shallow: true,\n * replaceUrl, or any external pushState/replaceState that changes the\n * query string). See router-init.ts.\n *\n * This replaces the previous useSyncExternalStore approach which read\n * window.location.search directly — causing React to detect external\n * store tearing during transitions and fall back to synchronous rendering\n * (renderRootSync instead of renderRootConcurrent), blocking the main\n * thread and freezing animations.\n *\n * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard\n * URLSearchParams. Mutation methods (set, delete, append) work on the\n * local copy but do NOT affect the URL — use the router or nuqs for that.\n *\n * During SSR, reads the request search params from the SSR ALS context\n * (populated by ssr-entry.ts) instead of window.location.\n *\n * Compatible with Next.js's `useSearchParams()` from `next/navigation`.\n */\n\nimport { getSsrData } from './ssr-data.js';\nimport { useNavigationContext } from './navigation-context.js';\nimport { cachedSearch, cachedSearchParams, _setCachedSearch } from './state.js';\n\nfunction getSearchParams(search: string): URLSearchParams {\n  if (search !== cachedSearch) {\n    const params = new URLSearchParams(search);\n    _setCachedSearch(search, params);\n    return params;\n  }\n  return cachedSearchParams;\n}\n\n/**\n * Read the current URL search params.\n *\n * Compatible with Next.js's `useSearchParams()` from `next/navigation`.\n */\nexport function useSearchParams(): URLSearchParams {\n  try {\n    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path\n    const navContext = useNavigationContext();\n    if (navContext !== null) {\n      return getSearchParams(navContext.search);\n    }\n  } catch {\n    // No React dispatcher available (called outside a component).\n  }\n\n  // SSR path: read from ALS-backed SSR data context.\n  const ssrData = getSsrData();\n  if (ssrData) return new URLSearchParams(ssrData.searchParams);\n\n  // Final fallback: window.location (tests, edge cases).\n  if (typeof window !== 'undefined') return getSearchParams(window.location.search);\n  return new URLSearchParams();\n}\n"],"mappings":";;;;;;;;;;;;;AA8CA,IAAa,eAAb,MAA0B;CACxB;CAEA,IAAI,SAA0C;EAC5C,IAAI,YAAY,OAAO,YAAY,KAAK,MAAM,SAC5C,OAAO,KAAK;CAGhB;CAEA,IAAI,SAAiB,MAAyB;EAC5C,IAAI,YAAY,OAAO,CAAC,KAAK,MAC3B,KAAK,OAAO;CAEhB;CAEA,QAAc;EACZ,KAAK,OAAO,KAAA;CACd;;;;;;;;;;;;;;CAeA,mBAAmB,iBAA0C;EAC3D,MAAM,WAAqB,CAAC;EAC5B,IAAI,KAAK,MACP,oBAAoB,KAAK,MAAM,UAAU,eAAe;EAE1D,OAAO,EAAE,SAAS;CACpB;AACF;;AAGA,SAAS,oBACP,MACA,KACA,iBACM;CACN,IAAI,CAAC,KAAK,YAAY,CAAC,mBAAmB,gBAAgB,IAAI,KAAK,OAAO,IACxE,IAAI,KAAK,KAAK,OAAO;CAEvB,KAAK,MAAM,SAAS,KAAK,SAAS,OAAO,GACvC,oBAAoB,OAAO,KAAK,eAAe;AAEnD;;;;;;;;;;;;AA0BA,SAAgB,iBAAiB,UAAkD;CAEjF,IAAI,SAAS,WAAW,GAAG,OAAO,KAAA;CAIlC,MAAM,UAAU,SAAS,SAAS,IAAI,SAAS,MAAM,GAAG,EAAE,IAAI;CAE9D,IAAI;CACJ,IAAI;CAEJ,KAAK,MAAM,QAAQ,SAAS;EAC1B,MAAM,KAAK,KAAK,aAAa,KAAK;EAClC,MAAM,OAAoB;GACxB,SAAS;GACT,SAAS;GACT,SAAS,KAAK;GACd,0BAAU,IAAI,IAAI;EACpB;EAEA,IAAI,CAAC,MACH,OAAO;EAGT,IAAI,QACF,OAAO,SAAS,IAAI,IAAI,IAAI;EAG9B,SAAS;CACX;CAEA,OAAO;AACT;;;;;;;;;AAiBA,IAAa,gBAAb,MAAa,cAAc;CACzB,OAAwB,SAAS;CACjC,0BAAkB,IAAI,IAA2B;CAEjD,IAAI,KAAa,QAA8B;EAC7C,KAAK,QAAQ,IAAI,KAAK;GACpB;GACA,WAAW,KAAK,IAAI,IAAI,cAAc;EACxC,CAAC;CACH;CAEA,IAAI,KAAyC;EAC3C,MAAM,QAAQ,KAAK,QAAQ,IAAI,GAAG;EAClC,IAAI,CAAC,OAAO,OAAO,KAAA;EACnB,IAAI,KAAK,IAAI,KAAK,MAAM,WAAW;GACjC,KAAK,QAAQ,OAAO,GAAG;GACvB;EACF;EACA,OAAO,MAAM;CACf;;CAGA,QAAQ,KAAyC;EAC/C,MAAM,SAAS,KAAK,IAAI,GAAG;EAC3B,IAAI,WAAW,KAAA,GACb,KAAK,QAAQ,OAAO,GAAG;EAEzB,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;ACzKA,IAAa,eAAb,MAA0B;CACxB,0BAAkB,IAAI,IAA0B;CAEhD,KAAK,KAAa,OAA2B;EAC3C,KAAK,QAAQ,IAAI,KAAK,KAAK;CAC7B;CAEA,IAAI,KAAuC;EACzC,OAAO,KAAK,QAAQ,IAAI,GAAG;CAC7B;CAEA,IAAI,KAAsB;EACxB,OAAO,KAAK,QAAQ,IAAI,GAAG;CAC7B;AACF;;;ACVA,IAAa,mBAAmB;;;;;AAQhC,SAAS,sBAA8B;CACrC,MAAM,QAAQ;CACd,IAAI,KAAK;CACT,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KACrB,MAAM,MAAO,KAAK,OAAO,IAAI,KAAM;CAErC,OAAO;AACT;;;;;;;;;AAUA,SAAS,eAAe,KAAqB;CAC3C,MAAM,YAAY,IAAI,QAAQ,GAAG;CACjC,MAAM,iBAAiB,cAAc,KAAK,MAAM,IAAI,MAAM,GAAG,SAAS;CAEtE,OAAO,GAAG,iBADQ,eAAe,SAAS,GAAG,IAAI,MAAM,IAClB,OAAO,oBAAoB;AAClE;;;;;;AASA,IAAI,qBAAoC;;AAexC,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;;;;AAMpC,SAAgB,kBAAkB,UAA6B;CAC7D,OAAO,SAAS,QAAQ,IAAI,aAAa,MAAM;AACjD;AAIA,SAAgB,gBACd,WACA,YACwB;CACxB,MAAM,UAAkC,EACtC,QAAQ,iBACV;CACA,IAAI,WACF,QAAQ,yBAAyB,KAAK,UAAU,SAAS;CAM3D,IAAI,YACF,QAAQ,kBAAkB;CAM5B,IAAI,oBACF,QAAQ,wBAAwB;CAElC,OAAO;AACT;;AAKA,SAAS,oBAAoB,YAAoB,KAAmB;CAClE,IAAA,QAAA,IAAA,aAA6B,cAAc;EACzC,MAAM,UAAU,IAAI,SAAS,MAAM,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM;EAC7D,QAAQ,KACN,sBAAsB,WAAW,gHACgD,SACnF;CACF;AACF;;;;;;;;;AAUA,SAAgB,mBAAmB,UAA0C;CAC3E,MAAM,SAAS,SAAS,QAAQ,IAAI,mBAAmB;CACvD,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI;EACF,OAAO,KAAK,MAAM,MAAM;CAC1B,QAAQ;EACN,oBAAoB,qBAAqB,MAAM;EAC/C,OAAO;CACT;AACF;;;;;;;;;AAUA,SAAgB,uBAAuB,UAAqC;CAC1E,MAAM,SAAS,SAAS,QAAQ,IAAI,2BAA2B;CAC/D,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI;EACF,MAAM,SAAS,KAAK,MAAM,MAAM;EAChC,OAAO,MAAM,QAAQ,MAAM,IAAI,SAAS;CAC1C,QAAQ;EACN,oBAAoB,6BAA6B,MAAM;EACvD,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,cAAc,UAA8D;CAC1F,MAAM,SAAS,SAAS,QAAQ,IAAI,iBAAiB;CACrD,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI;EACF,OAAO,KAAK,MAAM,MAAM;CAC1B,QAAQ;EACN,oBAAoB,mBAAmB,MAAM;EAC7C,OAAO;CACT;AACF;;;;;AAQA,IAAa,gBAAb,cAAmC,MAAM;CACvC;CACA,YAAY,KAAa;EACvB,MAAM,sBAAsB,KAAK;EACjC,KAAK,cAAc;CACrB;AACF;;;;;;AAOA,IAAa,mBAAb,cAAsC,MAAM;CAC1C,cAAc;EACZ,MAAM,oDAAoD;CAC5D;AACF;;;;;;;;;;AAWA,IAAa,sBAAb,cAAyC,MAAM;CAC7C;CACA;CACA,YAAY,QAAgB,KAAa;EACvC,MAAM,gBAAgB,OAAO,wBAAwB,KAAK;EAC1D,KAAK,SAAS;EACd,KAAK,MAAM;CACb;AACF;;;;;;;;;;;AAcA,SAAS,sBAAsB,MAG7B;CACA,IAAI;CACJ,IAAI;CACJ,MAAM,OAAO,IAAI,SAAe,KAAK,QAAQ;EAC3C,cAAc;EACd,aAAa;CACf,CAAC;CAED,MAAM,SAAS,KAAK,UAAU;CAsB9B,OAAO;EAAE,MAAM,IArBK,eAA2B;GAC7C,MAAM,KAAK,YAAY;IACrB,IAAI;KACF,MAAM,SAAS,MAAM,OAAO,KAAK;KACjC,IAAI,OAAO,MAAM;MACf,WAAW,MAAM;MACjB,YAAY;KACd,OACE,WAAW,QAAQ,OAAO,KAAK;IAEnC,SAAS,OAAO;KACd,WAAW,MAAM,KAAK;KACtB,WAAW,KAAK;IAClB;GACF;GACA,OAAO,QAAQ;IACb,OAAO,OAAO,MAAM;IACpB,YAAY;GACd;EACF,CAEe;EAAS;CAAK;AAC/B;;;;;;AASA,eAAsB,gBACpB,KACA,MACA,WACA,YACA,QACsB;CACtB,MAAM,SAAS,eAAe,GAAG;CACjC,MAAM,UAAU,gBAAgB,WAAW,UAAU;CACrD,IAAI,KAAK,WAAW;EAOlB,MAAM,eAAe,KAAK,MAAM,QAAQ;GAAE;GAAS,UAAU;GAAU;EAAO,CAAC;EAC/E,IAAI,cAAoC;EACxC,IAAI,SAAmD;EACvD,IAAI,kBAAmC;EAIvC,IAAI,aAA4B,QAAQ,QAAQ;EAEhD,MAAM,iBAAiB,aAAa,MAAM,aAAa;GAIrD,IAAI,kBAAkB,QAAQ,GAC5B,MAAM,IAAI,iBAAiB;GAM7B,MAAM,mBACJ,SAAS,QAAQ,IAAI,mBAAmB,MACvC,SAAS,UAAU,OAAO,SAAS,SAAS,MAAM,SAAS,QAAQ,IAAI,UAAU,IAAI;GACxF,IAAI,kBACF,MAAM,IAAI,cAAc,gBAAgB;GAM1C,IAAI,SAAS,QAAQ,IAAI,gBAAgB,MAAM,KAC7C,MAAM,IAAI,oBAAoB,SAAS,QAAQ,GAAG;GAIpD,cAAc,mBAAmB,QAAQ;GACzC,SAAS,cAAc,QAAQ;GAC/B,kBAAkB,uBAAuB,QAAQ;GAMjD,IAAI,SAAS,MAAM;IACjB,MAAM,UAAU,sBAAsB,SAAS,IAAI;IACnD,aAAa,QAAQ;IACrB,WAAW,YAAY,CAAC,CAAC;IACzB,OAAO,IAAI,SAAS,QAAQ,MAAM;KAChC,SAAS,SAAS;KAClB,QAAQ,SAAS;IACnB,CAAC;GACH;GACA,OAAO;EACT,CAAC;EAED,MAAM;EAKN,MAAM,UAAU,KAAK,UAAU,cAAc;EAM7C,MAAM,eAAe,IAAI,SAAe,GAAG,WAAW;GACpD,QAAQ,QAAQ,OAAO,CAAC,CAAC,WAAW,CAAC,GAAG,MAAM;EAChD,CAAC;EACD,aAAa,YAAY,CAAC,CAAC;EAE3B,OAAO;GACL;GACA,eAHoB,QAAQ,KAAK,CAAC,YAAY,YAAY,CAG1D;GACA;GACA;GACA;EACF;CACF;CAEA,MAAM,WAAW,MAAM,KAAK,MAAM,QAAQ;EAAE;EAAS,UAAU;EAAU;CAAO,CAAC;CAEjF,IAAI,SAAS,UAAU,OAAO,SAAS,SAAS,KAAK;EACnD,MAAM,WAAW,SAAS,QAAQ,IAAI,UAAU;EAChD,IAAI,UACF,MAAM,IAAI,cAAc,QAAQ;CAEpC;CACA,OAAO;EACL,SAAS,MAAM,SAAS,KAAK;EAC7B,eAAe;EACf,aAAa,mBAAmB,QAAQ;EACxC,QAAQ,cAAc,QAAQ;EAC9B,iBAAiB,uBAAuB,QAAQ;CAClD;AACF;;;;;;;ACxNA,SAAS,aAAa,OAAyB;CAC7C,IAAI,iBAAiB,gBAAgB,MAAM,SAAS,cAAc,OAAO;CACzE,IAAI,iBAAiB,SAAS,MAAM,SAAS,cAAc,OAAO;CAClE,OAAO;AACT;AAmBA,SAAgB,aAAa,MAAkC;CAC7D,MAAM,eAAe,IAAI,aAAa;CACtC,MAAM,gBAAgB,IAAI,cAAc;CACxC,MAAM,eAAe,IAAI,aAAa;CACtC,IAAI,cAA2B,EAAE,OAAO,OAAO;CAC/C,MAAM,mCAAmB,IAAI,IAAgC;CAM7D,IAAI,kBAA0C;;;;;;;;;;;;;;;CAgB9C,SAAS,eAAe,gBAA+C;EACrE,IAAI,iBAAiB;GACnB,gBAAgB,MAAM;GACtB,+BAA+B;GAC/B,KAAK,2BAA2B;EAClC;EACA,MAAM,aAAa,IAAI,gBAAgB;EACvC,kBAAkB;EAIlB,IAAI,gBACF,IAAI,eAAe,SACjB,WAAW,MAAM;OAEjB,eAAe,iBAAiB,eAAe,WAAW,MAAM,GAAG,EAAE,MAAM,KAAK,CAAC;EAIrF,OAAO;CACT;CAEA,SAAS,WAAW,OAAgB,KAAoB;EACtD,MAAM,OACJ,SAAS,MAAM;GAAE,OAAO;GAAc,WAAW;EAAI,IAAI,EAAE,OAAO,OAAO;EAE3E,IACE,YAAY,UAAU,KAAK,UAC1B,YAAY,UAAU,UACpB,YAAY,UAAU,gBACrB,KAAK,UAAU,gBACf,YAAY,cAAc,KAAK,YAEnC;EAEF,cAAc;EAId,KAAK,MAAM,YAAY,kBACrB,SAAS,KAAK;CAElB;;CAGA,SAAS,mBAAmB,aAAqD;EAC/E,IAAI,CAAC,eAAe,YAAY,WAAW,GAAG;EAC9C,MAAM,OAAO,iBAAiB,WAAW;EACzC,IAAI,MACF,aAAa,IAAI,KAAK,IAAI;CAE9B;;CAGA,SAAS,cAAc,SAAkB,UAAiC;EACxE,IAAI,KAAK,YACP,KAAK,WAAW,SAAS,QAAQ;CAErC;CAEA,SAAS,oBAAoB,iBAAuD;EAClF,OAAO,mBAAmB,QAAQ,gBAAgB,SAAS;CAC7D;;;;;CAMA,SAAS,oBAAoB,QAA2C;EACtE,MAAM,UAAU,IAAI,IAAI,OAAO,eAAgB;EAC/C,MAAM,cAAc,OAAO;EAC3B,MAAM,0BAAU,IAAI,IAAqB;EACzC,IAAI;QACG,MAAM,QAAQ,aACjB,IAAI,CAAC,QAAQ,IAAI,KAAK,aAAa,KAAK,IAAI,GAAG;IAG7C,QAAQ,IAAI,KAAK,aAAa,KAAK,MAAM,OAAO,OAAO;IACvD;GACF;;EAGJ,OAAO;CACT;;;;;;;;;CAUA,SAAS,sBACP,QACA,KACiB;EACjB,MAAM,iBAAiB,UAAU,CAAC;EAElC,iBAAiB,cAAc;EAE/B,MAAM,SAAS,IAAI,IAAI,KAAK,kBAAkB;EAG9C,MAAM,WAA4B;GAAE,QAAQ;GAAgB,UAF3C,OAAO,YAAY;GAEkC,QADvD,OAAO;EACuD;EAC7E,mBAAmB,QAAQ;EAC3B,OAAO;CACT;;;;;;;CAQA,eAAe,oBACb,KACA,SACe;EACf,IAAI,KAAK,oBAAoB;GAC3B,MAAM,KAAK,mBAAmB,KAAK,OAAO,gBAAgB;IACxD,MAAM,SAAS,MAAM,QAAQ;IAE7B,IAAI,oBAAoB,OAAO,eAAe,GAAG;KAC/C,MAAM,iBAAiB,oBAAoB,MAAM;KAEjD,aAAa,KAAK,KAAK;MACrB,SAAS;MACT,QAAQ,OAAO;KACjB,CAAC;KAUD,OAAO;MAAE,SALO,YACd,KAAK,qBAAqB,KAAK,OAAO,SACtC,OAAO,UACP,cAEO;MAAS,eAAe,OAAO;KAAc;IACxD;IAGA,aAAa,KAAK,KAAK;KACrB,SAAS,OAAO;KAChB,QAAQ,OAAO;IACjB,CAAC;IAED,OAAO;KAAE,SADO,YAAY,OAAO,SAAS,OAAO,QAC1C;KAAS,eAAe,OAAO;IAAc;GACxD,CAAC;GACD;EACF;EAEA,MAAM,SAAS,MAAM,QAAQ;EAC7B,IAAI,oBAAoB,OAAO,eAAe,GAC5C,aAAa,KAAK,KAAK;GACrB,SAAS;GACT,QAAQ,OAAO;EACjB,CAAC;OACI;GAIL,MAAM,UACJ,OAAO,WAAW,QAAQ,OAAO,OAAO,YAAY,YAAY,UAAU,OAAO,UAC7E,MAAO,OAAO,UACd,OAAO;GACb,aAAa,KAAK,KAAK;IACrB;IACA,QAAQ,OAAO;GACjB,CAAC;GACD,cAAc,SAAS,OAAO,QAAQ;EACxC;CACF;;CAGA,SAAS,WAAW,UAA4B;EAC9C,IAAI,KAAK,YACP,KAAK,WAAW,QAAQ;OAExB,SAAS;CAEb;;;;;CAMA,SAAS,wBAAwB,SAAuB;EACtD,iBAAiB;GACf,KAAK,SAAS,GAAG,OAAO;GACxB,OAAO,cAAc,IAAI,MAAM,wBAAwB,CAAC;EAC1D,CAAC;CACH;;;;;;;CAQA,SAAS,uBAAuB,MAAoB;EAClD,iBAAiB;GACf,IAAI,KAAK,eAAe,IAAI,MAAM,MAChC,KAAK,SAAS,GAAG,CAAC;GAEpB,OAAO,cAAc,IAAI,MAAM,wBAAwB,CAAC;EAC1D,CAAC;CACH;;;;;CAMA,eAAe,uBACb,KACA,SACsD;EAGtD,MAAM,aAAa,cAAc,QAAQ,GAAG;EAC5C,IAAI,SAAkC,aAClC;GACE,SAAS,WAAW;GACpB,eAAe;GACf,aAAa,WAAW,eAAe;GACvC,QAAQ,WAAW,UAAU;GAC7B,iBAAiB,WAAW,mBAAmB;EACjD,IACA,KAAA;EAEJ,IAAI,WAAW,KAAA,GAAW;GAGxB,MAAM,YAAY,aAAa,mBAAmB;GAClD,MAAM,gBAAgB,KAAK,cAAc;GAIzC,SAAS,MAAM,gBAAgB,KAAK,MAAM,WAHvB,cAAc,WAAW,MAAM,IAC9C,IAAI,IAAI,aAAa,CAAC,CAAC,WACvB,IAAI,IAAI,eAAe,kBAAkB,CAAC,CAAC,UACkB,QAAQ,MAAM;EACjF;EAMA,IAAI,CAAC,QAAQ,aAAa;GACxB,MAAM,YAAY,QAAQ,aAAa;GAGvC,KAAK,sBAAsB,IAAI;GAC/B,IAAI,QAAQ,SACV,KAAK,aAAa;IAAE,QAAQ;IAAM,SAAS;GAAE,GAAG,IAAI,SAAS;QAE7D,KAAK,UAAU;IAAE,QAAQ;IAAM,SAAS;GAAE,GAAG,IAAI,SAAS;GAE5D,KAAK,sBAAsB,KAAK;EAClC;EAQA,mBAAmB,OAAO,WAAW;EAGrC,MAAM,WAAW,sBAAsB,OAAO,QAAQ,GAAG;EAEzD,OAAO;GAAE,GAAG;GAAQ;EAAS;CAC/B;CAEA,eAAe,SAAS,KAAa,UAA6B,CAAC,GAAkB;EACnF,MAAM,SAAS,QAAQ,WAAW;EAClC,MAAM,UAAU,QAAQ,YAAY;EACpC,MAAM,iBAAiB,QAAQ;EAC/B,MAAM,cAAc,QAAQ,iBAAiB;EAO7C,MAAM,YAAY,IAAI,QAAQ,GAAG;EACjC,MAAM,OAAO,cAAc,KAAK,KAAK,IAAI,MAAM,SAAS;EACxD,MAAM,WAAW,cAAc,KAAK,MAAM,IAAI,MAAM,GAAG,SAAS;EAIhE,MAAM,WAAW,eAAe,cAAc;EAG9C,MAAM,iBAAiB,KAAK,WAAW;EAIvC,IAAI,KAAK,2BACP,KAAK,0BAA0B,cAAc;OAE7C,KAAK,aAAa;GAAE,QAAQ;GAAM,SAAS;EAAe,GAAG,IAAI,KAAK,cAAc,CAAC;EAUvF,IAAI,uBAAuB;EAC3B,IAAI,CAAC,eAAe,KAAK,oBAAoB;GAC3C,KAAK,sBAAsB,IAAI;GAC/B,KAAK,mBAAmB,KAAK,OAAO;GACpC,KAAK,sBAAsB,KAAK;GAChC,uBAAuB;EACzB;EAEA,WAAW,MAAM,GAAG;EAEpB,IAAI;GACF,MAAM,oBAAoB,gBACxB,uBAAuB,UAAU;IAC/B;IACA,WAAW;IACX,QAAQ,SAAS;IACjB,aAAa;GACf,CAAC,CACH;GAGA,OAAO,cAAc,IAAI,MAAM,uBAAuB,CAAC;GAMvD,IAAI,UAAU,MACZ,uBAAuB,IAAI;QAE3B,wBAAwB,SAAS,IAAI,cAAc;EAEvD,SAAS,OAAO;GAGd,IAAI,iBAAiB,kBAAkB;IACrC,kBAAkB,IAAI;IACtB,OAAO,SAAS,OAAO;IACvB,OAAO,IAAI,cAAc,CAAC,CAAC;GAC7B;GAGA,IAAI,iBAAiB,eAAe;IAIlC,IAAI,oBAAoB,UAAU;IAGlC,MAAM,SAAS,MAAM,aAAa,EAAE,SAAS,KAAK,CAAC;IACnD;GACF;GAUA,IAAI,iBAAiB,qBAAqB;IACxC,kBAAkB,IAAI;IACtB,OAAO,SAAS,OAAO,MAAM;IAC7B,OAAO,IAAI,cAAc,CAAC,CAAC;GAC7B;GAEA,IAAI,aAAa,KAAK,GAAG;GACzB,MAAM;EACR,UAAU;GASR,IAAI,oBAAoB,UAAU;IAMhC,kBAAkB;IAClB,WAAW,KAAK;IAIhB,KAAK,2BAA2B;GAClC;EACF;CACF;CAEA,eAAe,UAAyB;EACtC,MAAM,aAAa,KAAK,cAAc;EACtC,MAAM,WAAW,eAAe;EAEhC,WAAW,MAAM,UAAU;EAE3B,IAAI;GACF,MAAM,oBAAoB,YAAY,YAAY;IAEhD,MAAM,SAAS,MAAM,gBACnB,YACA,MACA,KAAA,GACA,KAAA,GACA,SAAS,MACX;IAEA,mBAAmB,OAAO,WAAW;IACrC,MAAM,WAAW,sBAAsB,OAAO,QAAQ,UAAU;IAChE,OAAO;KAAE,GAAG;KAAQ;IAAS;GAC/B,CAAC;EACH,SAAS,OAAO;GACd,IAAI,aAAa,KAAK,GAAG;GACzB,MAAM;EACR,UAAU;GAER,IAAI,oBAAoB,UAAU;IAChC,kBAAkB;IAClB,WAAW,KAAK;IAChB,KAAK,2BAA2B;GAClC;EACF;CACF;CAEA,eAAe,eACb,KACA,UAAkB,GAClB,gBACe;EAIf,MAAM,QAAQ,aAAa,IAAI,GAAG;EAElC,IAAI,SAAS,MAAM,YAAY,MAAM;GAUnC,eAAe,cAAc;GAC7B,kBAAkB;GAClB,WAAW,KAAK;GAChB,MAAM,WAAW,sBAAsB,MAAM,QAAQ,GAAG;GACxD,cAAc,MAAM,SAAS,QAAQ;GACrC,wBAAwB,OAAO;EACjC,OAAO;GAKL,MAAM,WAAW,eAAe,cAAc;GAC9C,WAAW,MAAM,GAAG;GACpB,IAAI;IACF,MAAM,oBAAoB,KAAK,YAAY;KAEzC,MAAM,SAAS,MAAM,gBAAgB,KAAK,MADxB,aAAa,mBACiB,GAAW,KAAA,GAAW,SAAS,MAAM;KACrF,mBAAmB,OAAO,WAAW;KACrC,MAAM,WAAW,sBAAsB,OAAO,QAAQ,GAAG;KAEzD,OAAO;MAAE,GAAG;MAAQ;KAAS;IAC/B,CAAC;IAED,wBAAwB,OAAO;GACjC,SAAS,OAAO;IACd,IAAI,aAAa,KAAK,GAAG;IACzB,MAAM;GACR,UAAU;IAER,IAAI,oBAAoB,UAAU;KAChC,kBAAkB;KAClB,WAAW,KAAK;IAClB;GACF;EACF;CACF;;;;;CAMA,SAAS,SAAS,KAAmB;EAGnC,MAAM,YAAY,IAAI,QAAQ,GAAG;EACjC,MAAM,WAAW,cAAc,KAAK,MAAM,IAAI,MAAM,GAAG,SAAS;EAGhE,IAAI,cAAc,IAAI,QAAQ,MAAM,KAAA,GAAW;EAC/C,IAAI,aAAa,IAAI,QAAQ,GAAG;EAIhC,gBAAqB,UAAU,MADb,aAAa,mBACM,CAAS,CAAC,CAAC,MAC7C,WAAW;GACV,OAAO,eAAe,YAAY,CAAC,CAAC;GACpC,cAAc,IAAI,UAAU,MAAM;EACpC,SACM,CAEN,CACF;CACF;CAEA,OAAO;EACL;EACA;EACA;EACA,iBAAiB,YAAY,UAAU;EACvC,qBAAsB,YAAY,UAAU,eAAe,YAAY,YAAY;EACnF,gBAAgB,UAAU;GACxB,iBAAiB,IAAI,QAAQ;GAC7B,aAAa,iBAAiB,OAAO,QAAQ;EAC/C;EACA;EACA,kBAAkB,SAAwB;GAMxC,MAAM,aAAa,KAAK,cAAc;GAKtC,MAAM,WAAW,mBAAmB;GAKpC,aAAa,KAAK,YAAY;IAC5B,SAAS;IACT,QAAQ,SAAS;GACnB,CAAC;GACD,cAAc,SAAS,QAAQ;EACjC;EACA,mBAAmB,aAA4B,mBAAmB,QAAQ;EAC1E;EACA;EACA;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACxwBA,SAAS,gBAAgB,QAAiC;CACxD,IAAI,WAAW,cAAc;EAC3B,MAAM,SAAS,IAAI,gBAAgB,MAAM;EACzC,iBAAiB,QAAQ,MAAM;EAC/B,OAAO;CACT;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAmC;CACjD,IAAI;EAEF,MAAM,aAAa,qBAAqB;EACxC,IAAI,eAAe,MACjB,OAAO,gBAAgB,WAAW,MAAM;CAE5C,QAAQ,CAER;CAGA,MAAM,UAAU,WAAW;CAC3B,IAAI,SAAS,OAAO,IAAI,gBAAgB,QAAQ,YAAY;CAG5D,IAAI,OAAO,WAAW,aAAa,OAAO,gBAAgB,OAAO,SAAS,MAAM;CAChF,OAAO,IAAI,gBAAgB;AAC7B"}

package/dist/client/link.d.ts

@@ -1,13 +1,20 @@
-import type { AnchorHTMLAttributes, ReactNode } from 'react';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
+import { type AnchorHTMLAttributes, type ReactNode } from 'react';
+import type { SearchParamsDefinition } from '../search-params/define.js';
+import type { LinkFunction } from './index.js';
+import { type UrlSegment } from '../routing/segment-classify.js';
+import { validateNavigationHref as validateLinkHref, isInternalHref } from '../shared/href-validation.js';
 export type OnNavigateEvent = {
     preventDefault: () => void;
 };
 export type OnNavigateHandler = (e: OnNavigateEvent) => void;
 /**
  * Base props shared by all Link variants.
+ *
+ * Exported so the public `LinkFunction` interface (declared in
+ * `./index.ts`, where module augmentation can merge into it) can
+ * compose this without duplication.
  */
-interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+export interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
     /** Prefetch the RSC payload on hover */
     prefetch?: boolean;
     /**
@@ -15,6 +22,20 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
      * Set to false for tabbed interfaces where content changes within a fixed layout.
      */
     scroll?: boolean;
+    /**
+     * Preserve search params from the current URL across navigation.
+     *
+     * - `true` — preserve ALL current search params (target params take precedence)
+     * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+     *
+     * Useful for route-group gating where a search param (e.g. `?private=access`)
+     * must persist across internal navigations. The target href's own search params
+     * always take precedence over preserved ones.
+     *
+     * During SSR, reads search params from the request context. On the client,
+     * reads from the current URL and updates reactively when the URL changes.
+     */
+    preserveSearchParams?: true | string[];
     /**
      * Called before client-side navigation commits. Call `e.preventDefault()`
      * to cancel the default navigation — the caller is then responsible for
@@ -27,48 +48,41 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
     children?: ReactNode;
 }
 /**
- * Link with a fully-resolved string href.
- * When using a string href with params already interpolated,
- * the params prop is not available.
+ * Widen server-side string params to string | number for Link convenience.
+ * Exported for use by codegen-generated overloads.
  */
-export interface LinkPropsWithHref extends LinkBaseProps {
-    href: string;
-    params?: never;
-    /**
-     * Typed search params — serialized via the route's SearchParamsDefinition.
-     * Mutually exclusive with an inline query string in href.
-     */
-    searchParams?: {
-        definition: SearchParamsDefinition<Record<string, unknown>>;
-        values: Record<string, unknown>;
-    };
-}
+export type LinkSegmentParams<T> = {
+    [K in keyof T]: [string] extends [T[K]] ? string | number : T[K];
+};
+export type ParamValue = string | number | string[] | {
+    toString(): string;
+    [key: string]: any;
+};
+type WrappedSearchParamsProp = {
+    definition: SearchParamsDefinition<Record<string, unknown>>;
+    values: Record<string, unknown>;
+};
+type FlatSearchParamsProp = Record<string, unknown>;
+type LinkSearchParamsProp = WrappedSearchParamsProp | FlatSearchParamsProp;
 /**
- * Link with a route pattern + params for interpolation.
- * e.g. <Link href="/products/[id]" params={{ id: "123" }}>
- *      <Link href="/products/[id]" params={{ id: 123 }}>
+ * Runtime-only loose props used internally by the Link implementation.
+ * Not exposed to callers — the public API uses LinkFunction.
  */
-export interface LinkPropsWithParams extends LinkBaseProps {
-    /** Route pattern with dynamic segments (e.g. "/products/[id]") */
+interface LinkRuntimeProps extends LinkBaseProps {
     href: string;
-    /**
-     * Dynamic segment values to interpolate into the href.
-     * Single dynamic segments accept string | number (numbers are stringified).
-     * Catch-all segments accept string[].
-     */
-    params: Record<string, string | number | string[]>;
-    /**
-     * Typed search params — serialized via the route's SearchParamsDefinition.
-     */
-    searchParams?: {
-        definition: SearchParamsDefinition<Record<string, unknown>>;
-        values: Record<string, unknown>;
-    };
+    segmentParams?: Record<string, ParamValue>;
+    searchParams?: LinkSearchParamsProp;
 }
-export type LinkProps = LinkPropsWithHref | LinkPropsWithParams;
-export declare function validateLinkHref(href: string): void;
-/** Returns true if the href is an internal path (not an external URL) */
-export declare function isInternalHref(href: string): boolean;
+export type LinkPropsWithHref = LinkBaseProps & {
+    href: string;
+    segmentParams?: never;
+    searchParams?: LinkSearchParamsProp;
+};
+export type LinkPropsWithParams = LinkRuntimeProps & {
+    segmentParams: Record<string, ParamValue>;
+};
+export type LinkProps = LinkRuntimeProps;
+export { validateLinkHref, isInternalHref };
 /**
  * Interpolate dynamic segments in a route pattern with actual values.
  * e.g. interpolateParams("/products/[id]", { id: "123" }) → "/products/123"
@@ -78,19 +92,13 @@ export declare function isInternalHref(href: string): boolean;
  * - [...param]       → catch-all (joined with /)
  * - [[...param]]     → optional catch-all (omitted if undefined/empty)
  */
-export declare function interpolateParams(pattern: string, params: Record<string, string | number | string[]>): string;
 /**
- * Resolve the final href string from Link props.
- *
- * Handles:
- * - params interpolation into route patterns
- * - searchParams serialization via SearchParamsDefinition
- * - Validation that searchParams and inline query strings are exclusive
+ * Parse a route pattern's path portion into classified segments.
+ * Exported for testing. Uses the shared character-based classifier.
  */
-export declare function resolveHref(href: string, params?: Record<string, string | number | string[]>, searchParams?: {
-    definition: SearchParamsDefinition<Record<string, unknown>>;
-    values: Record<string, unknown>;
-}): string;
+export declare function parseSegments(pattern: string): UrlSegment[];
+export declare function interpolateParams(pattern: string, params: Record<string, ParamValue>): string;
+export declare function resolveHref(href: string, params?: Record<string, ParamValue>, searchParams?: LinkSearchParamsProp): string;
 interface LinkOutputProps {
     href: string;
 }
@@ -99,11 +107,8 @@ interface LinkOutputProps {
  * for testability — the component just spreads these onto an <a>.
  */
 export declare function buildLinkProps(props: Pick<LinkPropsWithHref, 'href'> & {
-    params?: Record<string, string | number | string[]>;
-    searchParams?: {
-        definition: SearchParamsDefinition<Record<string, unknown>>;
-        values: Record<string, unknown>;
-    };
+    params?: Record<string, ParamValue>;
+    searchParams?: LinkSearchParamsProp;
 }): LinkOutputProps;
 /**
  * Navigation link with progressive enhancement.
@@ -113,10 +118,14 @@ export declare function buildLinkProps(props: Pick<LinkPropsWithHref, 'href'> &
  * navigation via the router. No global event delegation — each Link owns
  * its own click handling.
  *
- * Supports typed routes via codegen overloads. At runtime:
- * - `params` prop interpolates dynamic segments in the href pattern
+ * Supports typed routes via the Routes interface (populated by codegen).
+ * At runtime:
+ * - `segmentParams` prop interpolates dynamic segments in the href pattern
  * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
+ *
+ * Typed via the LinkFunction callable interface. The base call signature
+ * forbids segmentParams; per-route signatures are added by codegen via
+ * interface merging. See TIM-624.
  */
-export declare function Link({ href, prefetch, scroll, params, searchParams, onNavigate, onClick: userOnClick, onMouseEnter: userOnMouseEnter, children, ...rest }: LinkProps): import("react/jsx-runtime").JSX.Element;
-export {};
+export declare const Link: LinkFunction;
 //# sourceMappingURL=link.d.ts.map

package/dist/client/link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/client/link.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/client/link.tsx"],"names":[],"mappings":"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"}

package/dist/client/navigation-api.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Navigation API integration — progressive enhancement for client navigation.
+ *
+ * When the Navigation API (`window.navigation`) is available, this module
+ * provides an intercept-based navigation model that replaces the separate
+ * popstate + click handler approach with a single navigate event listener.
+ *
+ * Key benefits:
+ * - Intercepts ALL navigations (link clicks, form submissions, back/forward)
+ * - Built-in AbortSignal per navigation (auto-aborts in-flight fetches)
+ * - Per-entry state via NavigationHistoryEntry.getState()
+ * - navigation.transition for progress tracking
+ *
+ * When unavailable, all functions are no-ops and the History API fallback
+ * in browser-entry.ts handles navigation.
+ *
+ * See design/19-client-navigation.md
+ */
+/**
+ * Returns true if the Navigation API is available in the current environment.
+ * Feature-detected at runtime — no polyfill.
+ */
+export declare function hasNavigationApi(): boolean;
+/**
+ * Get the Navigation API instance. Returns null if unavailable.
+ */
+export declare function getNavigationApi(): Navigation | null;
+/**
+ * Callbacks for the Navigation API event handler.
+ *
+ * When the Navigation API intercepts a navigation, it delegates to these
+ * callbacks which run the RSC fetch + render pipeline.
+ */
+export interface NavigationApiCallbacks {
+    /**
+     * Handle a push/replace navigation intercepted by the Navigation API.
+     * This covers both Link <a> clicks (user-initiated) and external
+     * navigations (plain <a> tags, programmatic).
+     * The Navigation API handles the URL update via event.intercept().
+     */
+    onExternalNavigate: (url: string, options: {
+        replace: boolean;
+        signal: AbortSignal;
+        scroll?: boolean;
+    }) => Promise<void>;
+    /**
+     * Handle a traversal (back/forward button). The Navigation API intercepts
+     * the traversal and delegates to us for RSC replay/fetch.
+     */
+    onTraverse: (url: string, scrollY: number, signal: AbortSignal) => Promise<void>;
+    /**
+     * Called when a shallow URL update is intercepted (e.g., nuqs with
+     * shallow: true, or replaceUrl). The URL has already been committed —
+     * this callback syncs NavigationContext.search so useSearchParams()
+     * reflects the new value without a full router navigation.
+     */
+    onShallowNavigate?: (url: string) => void;
+}
+/**
+ * Controller returned by setupNavigationApi. Provides methods to
+ * coordinate between the router and the navigate event listener.
+ */
+export interface NavigationApiController {
+    /**
+     * Set the router-navigating flag. When `true`, the next navigate event
+     * (from pushState/replaceState) is recognized as router-initiated. The
+     * handler still intercepts it — but ties the browser's native loading
+     * state to a deferred promise instead of running the RSC pipeline again.
+     *
+     * This means `navigation.transition` is active for the full duration of
+     * every router-initiated navigation, giving the browser a native loading
+     * indicator (tab spinner, address bar) aligned with the TopLoader.
+     *
+     * Must be called synchronously around pushState/replaceState:
+     *   controller.setRouterNavigating(true);
+     *   history.pushState(...);        // navigate event fires, intercepted
+     *   controller.setRouterNavigating(false);  // flag off, deferred stays open
+     */
+    setRouterNavigating: (value: boolean) => void;
+    /**
+     * Resolve the deferred promise created by setRouterNavigating(true),
+     * clearing the browser's native loading state. Call this when the
+     * navigation fully completes — aligned with when the TopLoader's
+     * pendingUrl clears (same finally block in router.navigate).
+     */
+    completeRouterNavigation: () => void;
+    /**
+     * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+     * Unlike `history.pushState()`, this fires the navigate event BEFORE
+     * committing the URL — allowing Chrome to show its native loading
+     * indicator while the intercept handler runs.
+     *
+     * Must be called with setRouterNavigating(true) active so the handler
+     * recognizes it as router-initiated and uses the deferred promise.
+     */
+    navigate: (url: string, replace: boolean) => void;
+    /**
+     * Save scroll position into the current navigation entry's state.
+     * Uses navigation.updateCurrentEntry() for per-entry scroll storage.
+     */
+    saveScrollPosition: (scrollY: number) => void;
+    /**
+     * Check if the Navigation API has an active transition.
+     * Returns the transition object if available, null otherwise.
+     */
+    hasActiveTransition: () => boolean;
+    /** Remove the navigate event listener. */
+    cleanup: () => void;
+}
+/**
+ * Set up the Navigation API navigate event listener.
+ *
+ * Intercepts same-origin navigations and delegates to the provided callbacks.
+ * Router-initiated navigations (pushState from router.navigate) are detected
+ * via a synchronous flag and NOT intercepted — the router already handles them.
+ *
+ * Returns a controller for coordinating with the router.
+ */
+export declare function setupNavigationApi(callbacks: NavigationApiCallbacks): NavigationApiController;
+//# sourceMappingURL=navigation-api.d.ts.map

package/dist/client/navigation-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-api.d.ts","sourceRoot":"","sources":["../../src/client/navigation-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,GAAG,IAAI,CAGpD;AAID;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,kBAAkB,EAAE,CAClB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KACjE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB;;;OAGG;IACH,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjF;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAE9C;;;;;OAKG;IACH,wBAAwB,EAAE,MAAM,IAAI,CAAC;IAErC;;;;;;;;OAQG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAElD;;;OAGG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C;;;OAGG;IACH,mBAAmB,EAAE,MAAM,OAAO,CAAC;IAEnC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,sBAAsB,GAAG,uBAAuB,CAwM7F"}

package/dist/client/navigation-context.d.ts

@@ -3,7 +3,7 @@
  *
  * Holds the current route params and pathname, updated atomically
  * with the RSC tree on each navigation. This replaces the previous
- * useSyncExternalStore approach for useParams() and usePathname(),
+ * useSyncExternalStore approach for useSegmentParams() and usePathname(),
  * which suffered from a timing gap: the new tree could commit before
  * the external store re-renders fired, causing a frame where both
  * old and new active states were visible simultaneously.
@@ -40,11 +40,12 @@ import React, { type ReactNode } from 'react';
 export interface NavigationState {
     params: Record<string, string | string[]>;
     pathname: string;
+    search: string;
 }
 /**
  * Read the navigation context. Returns null during SSR (no provider)
  * or in the RSC environment (no context available).
- * Internal — used by useParams() and usePathname().
+ * Internal — used by useSegmentParams() and usePathname().
  */
 export declare function useNavigationContext(): NavigationState | null;
 export interface NavigationProviderProps {

package/dist/client/navigation-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuCD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAM7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AA6BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAKvD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAMrB"}
+{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AA2CD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAO7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AA8BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAMvD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAMrB"}