chore(bridge): prewarm hook, route key docs, quote retry rename

packages/interwovenkit-react/src/pages/bridge/BridgeFields.tsx

@@ -40,7 +40,10 @@ import { shouldWarnInsufficientFeeBalance } from "./data/fee-warning"
 import type { FormValues } from "./data/form"
 import { useBridgeForm } from "./data/form"
 import { calculateMinimumReceived, formatDuration, formatFees } from "./data/format"
-import { prefetchBridgeRoutePreparation, useBridgeRoutePreparation } from "./data/preparedRoute"
+import {
+  prefetchBridgeRoutePreparation,
+  useBridgeRoutePreparationPrewarm,
+} from "./data/preparedRoute"
 import { getBridgeRouteFreshnessMs, isBridgeQuoteFresh } from "./data/routeFreshness"
 import { useIsOpWithdrawable, useRouteErrorInfo, useRouteQuery } from "./data/simulate"
 import { useSkip } from "./data/skip"
@@ -165,8 +168,8 @@ const BridgeFields = () => {
   const { data: route, isLoading, error } = routeQuery
   const { data: routeErrorInfo } = useRouteErrorInfo(error)
   // Prewarm preparation queries (address list, tx, fee check, approvals) so the
-  // preview route loads from cache; return value is intentionally unused.
-  useBridgeRoutePreparation({
+  // preview route loads from cache.
+  useBridgeRoutePreparationPrewarm({
     route,
     values,
   })

packages/interwovenkit-react/src/pages/bridge/FooterWithMsgs.test.ts

@@ -1,4 +1,4 @@
-import { shouldRetryBridgeMsgsAfterQuoteRefresh } from "./data/messageRequestKey"
+import { shouldRetryBridgeMsgsAfterQuoteRefresh } from "./data/quoteRefreshRetry"
 
 describe("shouldRetryBridgeMsgsAfterQuoteRefresh", () => {
   it("retries when a refreshed quote arrives while preserving a stale preview", () => {

packages/interwovenkit-react/src/pages/bridge/FooterWithMsgs.tsx

@@ -2,8 +2,8 @@ import type { TxJson } from "@skip-go/client"
 import { type ReactNode, useEffect, useRef } from "react"
 import Button from "@/components/Button"
 import Footer from "@/components/Footer"
-import { shouldRetryBridgeMsgsAfterQuoteRefresh } from "./data/messageRequestKey"
 import { useBridgeTxQuery } from "./data/preparation"
+import { shouldRetryBridgeMsgsAfterQuoteRefresh } from "./data/quoteRefreshRetry"
 import type { SignedOpHook } from "./data/tx"
 import { useBridgePreviewState } from "./data/tx"
 import FooterWithError from "./FooterWithError"

packages/interwovenkit-react/src/pages/bridge/data/preparation.ts

@@ -11,8 +11,12 @@ import { InitiaAddress } from "@initia/utils"
 import { useChainEnabled } from "@/data/chains"
 import { fetchGasPrices } from "@/data/fee"
 import { normalizeError, STALE_TIMES } from "@/data/http"
-import { useAminoConverters, useAminoTypes, useCreateSigningStargateClient } from "@/data/signer"
-import { useOfflineSigner } from "@/data/signer"
+import {
+  useAminoConverters,
+  useAminoTypes,
+  useCreateSigningStargateClient,
+  useOfflineSigner,
+} from "@/data/signer"
 import { useInterwovenKit } from "@/public/data/hooks"
 import { useSkipBalancesQuery } from "./balance"
 import {
@@ -73,6 +77,11 @@ const queryKeys = createQueryKeys("interwovenkit:bridge-preparation", {
   }) => [params],
 })
 
+// Stable identity for React Query cache keys when building bridge txs from a route.
+// Intentionally narrower than `getRouteSignature` in `useRouteRefresh.ts`, which
+// compares many more fields (fees, warnings, USD, duration) to decide whether a
+// refreshed route "meaningfully" changed for preview navigation — do not unify
+// without revisiting both call sites.
 function getBridgePreparationRouteKey(route: RouterRouteResponseJson): string {
   return JSON.stringify({
     amount_in: route.amount_in,
@@ -399,7 +408,6 @@ export function useBridgeTxQuery(
   return useQuery({
     ...txOptions,
     enabled: !!route && !!addressList?.length && (!route.required_op_hook || !!signedOpHook),
-    staleTime: STALE_TIMES.MINUTE,
   })
 }
 

packages/interwovenkit-react/src/pages/bridge/data/preparedRoute.ts

@@ -144,7 +144,7 @@ export async function prefetchBridgeRoutePreparation({
   }
 }
 
-export function useBridgeRoutePreparation({ route, values, signedOpHook }: SharedOptions) {
+function useBridgeRoutePreparationInternal({ route, values, signedOpHook }: SharedOptions) {
   const addressListQuery = useBridgeAddressListQuery(route, values, { background: true })
   const txQuery = useBridgeTxQuery(route, values, addressListQuery.data, signedOpHook)
   const exactFeeQuery = useExactFeeCheckQuery(route, values, txQuery.data)
@@ -168,3 +168,8 @@ export function useBridgeRoutePreparation({ route, values, signedOpHook }: Share
     tx: txQuery.data,
   })
 }
+
+/** Runs preparation queries in the background; return value is unused by design. */
+export function useBridgeRoutePreparationPrewarm(props: SharedOptions): void {
+  void useBridgeRoutePreparationInternal(props)
+}

packages/interwovenkit-react/src/pages/bridge/data/useRouteRefresh.ts

@@ -20,6 +20,10 @@ function toDeterministicString(value: unknown): string {
     .join(",")}}`
 }
 
+// Detects user-visible route changes after a manual refresh (preview).
+// Broader than `getBridgePreparationRouteKey` in `preparation.ts`, which only
+// keys tx-building cache — keep the two signatures distinct unless both flows
+// are re-audited together.
 function getRouteSignature(route: RouterRouteResponseJson) {
   return toDeterministicString({
     amount_in: route.amount_in,