From 390dafb6096b215e0f2df7f9dbf987b623169d6a Mon Sep 17 00:00:00 2001
From: gudnuf <gudnuf21@proton.me>
Date: Fri, 30 Jan 2026 14:04:48 -0800
Subject: [PATCH] refactor how we use the redirectTo param

---
 app/features/gift-cards/gift-card-details.tsx |  4 +-
 app/features/receive/index.ts                 | 15 ++-
 app/features/receive/receive-cashu-token.tsx  | 19 ++--
 app/features/receive/receive-cashu.tsx        | 25 ++---
 app/features/receive/receive-flow.tsx         | 93 ++++++++++++++++++
 app/features/receive/receive-input.tsx        | 40 ++++----
 app/features/receive/receive-spark.tsx        | 25 ++---
 app/features/receive/scan.tsx                 | 15 +--
 app/features/send/send-confirmation.tsx       | 46 +++++++--
 app/features/send/send-input.tsx              | 12 ++-
 app/features/send/send-scanner.tsx            | 12 ++-
 app/features/send/share-cashu-token.tsx       | 10 +-
 .../transactions/transaction-details.tsx      |  8 +-
 app/hooks/use-redirect-to.ts                  | 72 ++++++++++++++
 app/lib/transitions/view-transition.tsx       |  4 +-
 .../_protected.receive.cashu_.token.tsx       |  3 +-
 app/routes/_protected.receive.tsx             | 94 ++++++++++++++++++-
 app/routes/_protected.send.share.$swapId.tsx  | 22 ++++-
 ...protected.transactions.$transactionId_.tsx | 12 +--
 app/routes/_public.mint-risks.tsx             |  9 +-
 app/routes/_public.privacy.tsx                |  9 +-
 app/routes/_public.terms.tsx                  |  9 +-
 22 files changed, 432 insertions(+), 126 deletions(-)
 create mode 100644 app/features/receive/receive-flow.tsx
 create mode 100644 app/hooks/use-redirect-to.ts

diff --git a/app/features/gift-cards/gift-card-details.tsx b/app/features/gift-cards/gift-card-details.tsx
index ed9f20d7f..fb762f029 100644
--- a/app/features/gift-cards/gift-card-details.tsx
+++ b/app/features/gift-cards/gift-card-details.tsx
@@ -150,14 +150,14 @@ export default function GiftCardDetails({ cardId }: GiftCardDetailsProps) {
 
           <div className="mt-6 grid w-72 grid-cols-2 gap-10">
             <LinkWithViewTransition
-              to={`/receive?accountId=${card.id}`}
+              to={`/receive?accountId=${card.id}&redirectTo=${encodeURIComponent(`/gift-cards/${card.id}`)}`}
               transition="slideUp"
               applyTo="newView"
             >
               <Button className="w-full px-7 py-6 text-lg">Add</Button>
             </LinkWithViewTransition>
             <LinkWithViewTransition
-              to={`/send?accountId=${card.id}`}
+              to={`/send?accountId=${card.id}&redirectTo=${encodeURIComponent(`/gift-cards/${card.id}`)}`}
               transition="slideUp"
               applyTo="newView"
             >
diff --git a/app/features/receive/index.ts b/app/features/receive/index.ts
index ebb28b96b..a24bce744 100644
--- a/app/features/receive/index.ts
+++ b/app/features/receive/index.ts
@@ -1,6 +1,19 @@
 import ReceiveCashu from './receive-cashu';
 import ReceiveCashuToken from './receive-cashu-token';
+import {
+  type ReceiveFlowDefinition,
+  ReceiveFlowProvider,
+  useReceiveFlowStep,
+} from './receive-flow';
 import ReceiveInput from './receive-input';
 import { ReceiveProvider } from './receive-provider';
 
-export { ReceiveInput, ReceiveCashuToken, ReceiveCashu, ReceiveProvider };
+export {
+  ReceiveInput,
+  ReceiveCashuToken,
+  ReceiveCashu,
+  ReceiveProvider,
+  ReceiveFlowProvider,
+  useReceiveFlowStep,
+};
+export type { ReceiveFlowDefinition };
diff --git a/app/features/receive/receive-cashu-token.tsx b/app/features/receive/receive-cashu-token.tsx
index bf351eb8a..e969c239a 100644
--- a/app/features/receive/receive-cashu-token.tsx
+++ b/app/features/receive/receive-cashu-token.tsx
@@ -21,10 +21,7 @@ import { Button } from '~/components/ui/button';
 import { useToast } from '~/hooks/use-toast';
 import { useFeatureFlag } from '~/lib/feature-flags';
 import type { Currency } from '~/lib/money';
-import {
-  LinkWithViewTransition,
-  useNavigateWithViewTransition,
-} from '~/lib/transitions';
+import { LinkWithViewTransition } from '~/lib/transitions';
 import { AccountSelector } from '../accounts/account-selector';
 import { GiftCardItem } from '../gift-cards/gift-card-item';
 import { getGiftCardImageByUrl } from '../gift-cards/use-discover-cards';
@@ -45,6 +42,7 @@ import {
   type ReceiveCashuTokenAccount,
   isClaimingToSameCashuAccount,
 } from './receive-cashu-token-models';
+import { useReceiveFlowStep } from './receive-flow';
 
 type Props = {
   token: Token;
@@ -104,7 +102,7 @@ export default function ReceiveToken({
   preferredReceiveAccountId,
 }: Props) {
   const { toast } = useToast();
-  const navigate = useNavigateWithViewTransition();
+  const { back, onSuccess } = useReceiveFlowStep('claimCashuToken');
   const { claimableToken, cannotClaimReason } =
     useCashuTokenWithClaimableProofs({ token });
   const {
@@ -160,10 +158,7 @@ export default function ReceiveToken({
       return result.lightningReceiveQuote.transactionId;
     },
     onSuccess: (transactionId) => {
-      navigate(`/transactions/${transactionId}?redirectTo=/`, {
-        transition: 'slideLeft',
-        applyTo: 'newView',
-      });
+      onSuccess(transactionId);
     },
     onError: (error) => {
       console.error('Error claiming token', { cause: error });
@@ -179,9 +174,9 @@ export default function ReceiveToken({
     <>
       <PageHeader className="z-10">
         <PageBackButton
-          to="/receive"
-          transition="slideRight"
-          applyTo="oldView"
+          to={back.to}
+          transition={back.transition}
+          applyTo={back.applyTo}
         />
         <PageHeaderTitle>Receive</PageHeaderTitle>
       </PageHeader>
diff --git a/app/features/receive/receive-cashu.tsx b/app/features/receive/receive-cashu.tsx
index 6e0987f98..16d50f833 100644
--- a/app/features/receive/receive-cashu.tsx
+++ b/app/features/receive/receive-cashu.tsx
@@ -15,10 +15,7 @@ import type { CashuAccount } from '~/features/accounts/account';
 import { useEffectNoStrictMode } from '~/hooks/use-effect-no-strict-mode';
 import { useToast } from '~/hooks/use-toast';
 import type { Money } from '~/lib/money';
-import {
-  LinkWithViewTransition,
-  useNavigateWithViewTransition,
-} from '~/lib/transitions';
+import { LinkWithViewTransition } from '~/lib/transitions';
 import { getDefaultUnit } from '../shared/currencies';
 import { MoneyWithConvertedAmount } from '../shared/money-with-converted-amount';
 import type { CashuReceiveQuote } from './cashu-receive-quote';
@@ -26,6 +23,7 @@ import {
   useCashuReceiveQuote,
   useCreateCashuReceiveQuote,
 } from './cashu-receive-quote-hooks';
+import { useReceiveFlowStep } from './receive-flow';
 
 type CreateQuoteProps = {
   account: CashuAccount;
@@ -110,16 +108,13 @@ export default function ReceiveCashu({ amount, account }: Props) {
   const [showOk, setShowOk] = useState(false);
   const [, copyToClipboard] = useCopyToClipboard();
   const { toast } = useToast();
-  const navigate = useNavigateWithViewTransition();
+  const { back, onSuccess } = useReceiveFlowStep('cashuLightningInvoice');
 
   const { quote, errorMessage, isLoading } = useCreateQuote({
     account,
     amount,
     onPaid: (quote) => {
-      navigate(`/transactions/${quote.transactionId}?redirectTo=/`, {
-        transition: 'fade',
-        applyTo: 'newView',
-      });
+      onSuccess(quote.transactionId);
     },
   });
 
@@ -141,9 +136,9 @@ export default function ReceiveCashu({ amount, account }: Props) {
     <>
       <PageHeader>
         <ClosePageButton
-          to="/receive"
-          transition="slideDown"
-          applyTo="oldView"
+          to={back.to}
+          transition={back.transition}
+          applyTo={back.applyTo}
         />
         <PageHeaderTitle>Receive Ecash</PageHeaderTitle>
       </PageHeader>
@@ -172,9 +167,9 @@ export default function ReceiveCashu({ amount, account }: Props) {
         <PageFooter className="pb-14">
           <Button asChild className="w-[80px]">
             <LinkWithViewTransition
-              to="/"
-              transition="slideDown"
-              applyTo="oldView"
+              to={back.to}
+              transition={back.transition}
+              applyTo={back.applyTo}
             >
               OK
             </LinkWithViewTransition>
diff --git a/app/features/receive/receive-flow.tsx b/app/features/receive/receive-flow.tsx
new file mode 100644
index 000000000..6ad6bcfb4
--- /dev/null
+++ b/app/features/receive/receive-flow.tsx
@@ -0,0 +1,93 @@
+import { type PropsWithChildren, createContext, useContext } from 'react';
+import type { ApplyTo, Transition } from '~/lib/transitions';
+
+/**
+ * A navigation action with destination and animation.
+ * The `to` is an object with pathname and search to ensure we can spread hash into it.
+ */
+export type NavAction = {
+  to: { pathname: string; search: string };
+  transition: Transition;
+  applyTo: ApplyTo;
+};
+
+/** Dynamic navigation action that requires parameters */
+type DynamicNavAction<T extends unknown[]> = (...args: T) => NavAction;
+
+/**
+ * The complete receive flow definition.
+ * Step and action names are self-documenting to describe the flow structure.
+ */
+export type ReceiveFlowDefinition = {
+  amountInput: {
+    close: NavAction;
+    next: {
+      cashuLightningInvoice: NavAction;
+      sparkLightningInvoice: NavAction;
+    };
+    actions: {
+      scanToken: NavAction;
+      claimCashuToken: DynamicNavAction<[string]>;
+    };
+  };
+  scanToken: {
+    back: NavAction;
+    next: {
+      claimCashuToken: DynamicNavAction<[string]>;
+    };
+  };
+  cashuLightningInvoice: {
+    back: NavAction;
+    onSuccess: (transactionId: string) => void;
+  };
+  sparkLightningInvoice: {
+    back: NavAction;
+    onSuccess: (transactionId: string) => void;
+  };
+  claimCashuToken: {
+    back: NavAction;
+    onSuccess: (transactionId: string) => void;
+  };
+};
+
+const ReceiveFlowContext = createContext<ReceiveFlowDefinition | null>(null);
+
+type ReceiveFlowProviderProps = PropsWithChildren<{
+  flow: ReceiveFlowDefinition;
+}>;
+
+/**
+ * Provider that makes the receive flow navigation available to all child components.
+ * Should be used in the receive layout to wrap the Outlet.
+ */
+export const ReceiveFlowProvider = ({
+  flow,
+  children,
+}: ReceiveFlowProviderProps) => {
+  return (
+    <ReceiveFlowContext.Provider value={flow}>
+      {children}
+    </ReceiveFlowContext.Provider>
+  );
+};
+
+/**
+ * Hook for components to get their step's navigation actions.
+ * Components think in terms of back/next/close.
+ *
+ * @example
+ * const { close, next, actions } = useReceiveFlowStep('amountInput');
+ * <ClosePageButton {...close} />
+ * navigate(next.cashuLightningInvoice.to, { transition: next.cashuLightningInvoice.transition });
+ */
+export function useReceiveFlowStep<K extends keyof ReceiveFlowDefinition>(
+  stepName: K,
+): ReceiveFlowDefinition[K] {
+  const flow = useContext(ReceiveFlowContext);
+  if (!flow) {
+    throw new Error(
+      'useReceiveFlowStep must be used within ReceiveFlowProvider',
+    );
+  }
+  return flow[stepName];
+}
diff --git a/app/features/receive/receive-input.tsx b/app/features/receive/receive-input.tsx
index 36f7c4f69..3baa007e3 100644
--- a/app/features/receive/receive-input.tsx
+++ b/app/features/receive/receive-input.tsx
@@ -28,6 +28,7 @@ import {
   useNavigateWithViewTransition,
 } from '~/lib/transitions';
 import { useAccount, useAccounts } from '../accounts/account-hooks';
+import { useReceiveFlowStep } from './receive-flow';
 import { useReceiveStore } from './receive-provider';
 
 type ConvertedMoneySwitcherProps = {
@@ -63,6 +64,7 @@ const ConvertedMoneySwitcher = ({
 export default function ReceiveInput() {
   const navigate = useNavigateWithViewTransition();
   const { toast } = useToast();
+  const { close, next, actions } = useReceiveFlowStep('amountInput');
   const { animationClass: shakeAnimationClass, start: startShakeAnimation } =
     useAnimation({ name: 'shake' });
 
@@ -104,17 +106,14 @@ export default function ReceiveInput() {
       setReceiveAmount(convertedValue);
     }
 
-    if (receiveAccount.type === 'cashu') {
-      navigate('/receive/cashu', {
-        transition: 'slideLeft',
-        applyTo: 'newView',
-      });
-    } else {
-      navigate('/receive/spark', {
-        transition: 'slideLeft',
-        applyTo: 'newView',
-      });
-    }
+    const nextStep =
+      receiveAccount.type === 'cashu'
+        ? next.cashuLightningInvoice
+        : next.sparkLightningInvoice;
+    navigate(nextStep.to, {
+      transition: nextStep.transition,
+      applyTo: nextStep.applyTo,
+    });
   };
 
   const handlePaste = async () => {
@@ -139,11 +138,12 @@ export default function ReceiveInput() {
     // The hash needs to be set manually before navigating or clientLoader of the destination route won't see it
     // See https://github.com/remix-run/remix/discussions/10721
     window.history.replaceState(null, '', hash);
+    const tokenAction = actions.claimCashuToken(receiveAccountId);
     navigate(
-      `/receive/cashu/token?selectedAccountId=${receiveAccountId}${hash}`,
+      { ...tokenAction.to, hash },
       {
-        transition: 'slideLeft',
-        applyTo: 'newView',
+        transition: tokenAction.transition,
+        applyTo: tokenAction.applyTo,
       },
     );
   };
@@ -151,7 +151,11 @@ export default function ReceiveInput() {
   return (
     <>
       <PageHeader>
-        <ClosePageButton to="/" transition="slideDown" applyTo="oldView" />
+        <ClosePageButton
+          to={close.to}
+          transition={close.transition}
+          applyTo={close.applyTo}
+        />
         <PageHeaderTitle>Receive</PageHeaderTitle>
       </PageHeader>
 
@@ -197,9 +201,9 @@ export default function ReceiveInput() {
               </button>
 
               <LinkWithViewTransition
-                to="/receive/scan"
-                transition="slideUp"
-                applyTo="newView"
+                to={actions.scanToken.to}
+                transition={actions.scanToken.transition}
+                applyTo={actions.scanToken.applyTo}
               >
                 <Scan />
               </LinkWithViewTransition>
diff --git a/app/features/receive/receive-spark.tsx b/app/features/receive/receive-spark.tsx
index f94b4d626..1b883a640 100644
--- a/app/features/receive/receive-spark.tsx
+++ b/app/features/receive/receive-spark.tsx
@@ -12,12 +12,10 @@ import { Button } from '~/components/ui/button';
 import { useEffectNoStrictMode } from '~/hooks/use-effect-no-strict-mode';
 import { useToast } from '~/hooks/use-toast';
 import type { Money } from '~/lib/money';
-import {
-  LinkWithViewTransition,
-  useNavigateWithViewTransition,
-} from '~/lib/transitions';
+import { LinkWithViewTransition } from '~/lib/transitions';
 import type { SparkAccount } from '../accounts/account';
 import { MoneyWithConvertedAmount } from '../shared/money-with-converted-amount';
+import { useReceiveFlowStep } from './receive-flow';
 import type { SparkReceiveQuote } from './spark-receive-quote';
 import {
   useCreateSparkReceiveQuote,
@@ -68,19 +66,16 @@ const useCreateQuote = ({
 };
 
 export default function ReceiveSpark({ amount, account }: Props) {
-  const navigate = useNavigateWithViewTransition();
   const [showOk, setShowOk] = useState(false);
   const [, copyToClipboard] = useCopyToClipboard();
   const { toast } = useToast();
+  const { back, onSuccess } = useReceiveFlowStep('sparkLightningInvoice');
 
   const { quote, errorMessage, isLoading } = useCreateQuote({
     account,
     amount,
     onPaid: (quote) => {
-      navigate(`/transactions/${quote.transactionId}?redirectTo=/`, {
-        transition: 'fade',
-        applyTo: 'newView',
-      });
+      onSuccess(quote.transactionId);
     },
   });
 
@@ -98,9 +93,9 @@ export default function ReceiveSpark({ amount, account }: Props) {
     <>
       <PageHeader>
         <ClosePageButton
-          to="/receive"
-          transition="slideDown"
-          applyTo="oldView"
+          to={back.to}
+          transition={back.transition}
+          applyTo={back.applyTo}
         />
         <PageHeaderTitle>Receive</PageHeaderTitle>
       </PageHeader>
@@ -118,9 +113,9 @@ export default function ReceiveSpark({ amount, account }: Props) {
         <PageFooter className="pb-14">
           <Button asChild className="w-[80px]">
             <LinkWithViewTransition
-              to="/"
-              transition="slideDown"
-              applyTo="oldView"
+              to={back.to}
+              transition={back.transition}
+              applyTo={back.applyTo}
             >
               OK
             </LinkWithViewTransition>
diff --git a/app/features/receive/scan.tsx b/app/features/receive/scan.tsx
index 8219e16d0..e930a32d2 100644
--- a/app/features/receive/scan.tsx
+++ b/app/features/receive/scan.tsx
@@ -9,20 +9,22 @@ import { QRScanner } from '~/components/qr-scanner';
 import { useToast } from '~/hooks/use-toast';
 import { extractCashuToken } from '~/lib/cashu';
 import { useNavigateWithViewTransition } from '~/lib/transitions';
+import { useReceiveFlowStep } from './receive-flow';
 import { useReceiveStore } from './receive-provider';
 
 export default function Scan() {
   const { toast } = useToast();
   const navigate = useNavigateWithViewTransition();
+  const { back, next } = useReceiveFlowStep('scanToken');
   const receiveAccountId = useReceiveStore((s) => s.accountId);
 
   return (
     <>
       <PageHeader className="z-10">
         <PageBackButton
-          to="/receive"
-          transition="slideDown"
-          applyTo="oldView"
+          to={back.to}
+          transition={back.transition}
+          applyTo={back.applyTo}
         />
         <PageHeaderTitle>Scan</PageHeaderTitle>
       </PageHeader>
@@ -45,11 +47,12 @@ export default function Scan() {
             // The hash needs to be set manually before navigating or clientLoader of the destination route won't see it
             // See https://github.com/remix-run/remix/discussions/10721
             window.history.replaceState(null, '', hash);
+            const tokenAction = next.claimCashuToken(receiveAccountId);
             navigate(
-              `/receive/cashu/token?selectedAccountId=${receiveAccountId}${hash}`,
+              { ...tokenAction.to, hash },
               {
-                transition: 'slideLeft',
-                applyTo: 'newView',
+                transition: tokenAction.transition,
+                applyTo: tokenAction.applyTo,
               },
             );
           }}
diff --git a/app/features/send/send-confirmation.tsx b/app/features/send/send-confirmation.tsx
index 08c810a24..5fe03c379 100644
--- a/app/features/send/send-confirmation.tsx
+++ b/app/features/send/send-confirmation.tsx
@@ -10,6 +10,7 @@ import { Card, CardContent } from '~/components/ui/card';
 import type { CashuAccount, SparkAccount } from '~/features/accounts/account';
 import type { CashuLightningQuote } from '~/features/send/cashu-send-quote-service';
 import { MoneyWithConvertedAmount } from '~/features/shared/money-with-converted-amount';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { useToast } from '~/hooks/use-toast';
 import { decodeBolt11 } from '~/lib/bolt11';
 import type { Money } from '~/lib/money';
@@ -51,10 +52,16 @@ const BaseConfirmation = ({
   loading?: boolean;
   error?: string;
 }) => {
+  const { buildTo } = useRedirectTo('/');
+
   return (
     <Page>
       <PageHeader className="z-10">
-        <PageBackButton to="/send" transition="slideDown" applyTo="oldView" />
+        <PageBackButton
+          to={buildTo('/send')}
+          transition="slideDown"
+          applyTo="oldView"
+        />
         <PageHeaderTitle>Confirm Payment</PageHeaderTitle>
       </PageHeader>
       <PageContent className="flex flex-col items-center gap-4">
@@ -92,18 +99,22 @@ type UsePayBolt11Props = {
   quote: CashuLightningQuote | SparkLightningQuote;
   /** Additional details about the destination to include in the Agicash DB record.*/
   destinationDetails?: DestinationDetails;
+  /** Where to redirect after the transaction is complete. */
+  redirectTo: string;
 };
 
 /**
  * A hook that is used to pay bolt11 invoices from a Cashu account or a Spark account.
  * @param account - The account to send from.
  * @param quote - The quote to pay
+ * @param redirectTo - Where to redirect after the transaction is complete.
  * @returns A function to handle the confirmation of the payment and a boolean indicating if the payment is pending.
  */
 const usePayBolt11 = ({
   account,
   quote,
   destinationDetails,
+  redirectTo,
 }: UsePayBolt11Props) => {
   const { toast } = useToast();
   const navigate = useNavigateWithViewTransition();
@@ -111,10 +122,16 @@ const usePayBolt11 = ({
   const { mutate: initiateCashuSend, status: initiateCashuSendQuoteStatus } =
     useInitiateCashuSendQuote({
       onSuccess: (data) => {
-        navigate(`/transactions/${data.transactionId}?redirectTo=/`, {
-          transition: 'slideLeft',
-          applyTo: 'newView',
-        });
+        navigate(
+          {
+            pathname: `/transactions/${data.transactionId}`,
+            search: `?redirectTo=${encodeURIComponent(redirectTo)}`,
+          },
+          {
+            transition: 'slideLeft',
+            applyTo: 'newView',
+          },
+        );
       },
       onError: (error) => {
         if (error instanceof DomainError) {
@@ -133,10 +150,16 @@ const usePayBolt11 = ({
   const { mutate: initiateSparkSend, status: initiateSparkSendQuoteStatus } =
     useInitiateSparkSendQuote({
       onSuccess: (sendQuote) => {
-        navigate(`/transactions/${sendQuote.transactionId}?redirectTo=/`, {
-          transition: 'slideLeft',
-          applyTo: 'newView',
-        });
+        navigate(
+          {
+            pathname: `/transactions/${sendQuote.transactionId}`,
+            search: `?redirectTo=${encodeURIComponent(redirectTo)}`,
+          },
+          {
+            transition: 'slideLeft',
+            applyTo: 'newView',
+          },
+        );
       },
       onError: (error) => {
         console.error('Failed to initiate spark send', { cause: error });
@@ -197,10 +220,12 @@ export const PayBolt11Confirmation = ({
   destinationDisplay,
   destinationDetails,
 }: PayBolt11ConfirmationProps) => {
+  const { redirectTo } = useRedirectTo('/');
   const { handleConfirm, isPending } = usePayBolt11({
     account,
     quote: bolt11Quote,
     destinationDetails,
+    redirectTo,
   });
 
   const { description } = decodeBolt11(destination);
@@ -266,11 +291,12 @@ export const CreateCashuTokenConfirmation = ({
 }: CreateCashuTokenConfirmationProps) => {
   const navigate = useNavigateWithViewTransition();
   const { toast } = useToast();
+  const { buildTo } = useRedirectTo('/');
 
   const { mutate: createCashuSendSwap, status: createSwapStatus } =
     useCreateCashuSendSwap({
       onSuccess: (swap) => {
-        navigate(`/send/share/${swap.id}`, {
+        navigate(buildTo(`/send/share/${swap.id}`), {
           transition: 'slideUp',
           applyTo: 'newView',
         });
diff --git a/app/features/send/send-input.tsx b/app/features/send/send-input.tsx
index c6015c8b4..58797d39b 100644
--- a/app/features/send/send-input.tsx
+++ b/app/features/send/send-input.tsx
@@ -35,6 +35,7 @@ import {
 import { accountOfflineToast } from '~/features/accounts/utils';
 import useAnimation from '~/hooks/use-animation';
 import { useMoneyInput } from '~/hooks/use-money-input';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { useToast } from '~/hooks/use-toast';
 import { buildLightningAddressFormatValidator } from '~/lib/lnurl';
 import type { Money } from '~/lib/money';
@@ -84,6 +85,7 @@ const ConvertedMoneySwitcher = ({
 export function SendInput() {
   const { toast } = useToast();
   const navigate = useNavigateWithViewTransition();
+  const { redirectTo, buildTo } = useRedirectTo('/');
   const { animationClass: shakeAnimationClass, start: startShakeAnimation } =
     useAnimation({ name: 'shake' });
   const { data: accounts } = useAccounts();
@@ -155,7 +157,7 @@ export function SendInput() {
       return;
     }
 
-    navigate('/send/confirm', {
+    navigate(buildTo('/send/confirm'), {
       applyTo: 'newView',
       transition: 'slideLeft',
     });
@@ -203,7 +205,11 @@ export function SendInput() {
   return (
     <>
       <PageHeader>
-        <ClosePageButton to="/" transition="slideDown" applyTo="oldView" />
+        <ClosePageButton
+          to={redirectTo}
+          transition="slideDown"
+          applyTo="oldView"
+        />
         <PageHeaderTitle>Send</PageHeaderTitle>
       </PageHeader>
 
@@ -263,7 +269,7 @@ export function SendInput() {
               </button>
 
               <LinkWithViewTransition
-                to="/send/scan"
+                to={buildTo('/send/scan')}
                 transition="slideUp"
                 applyTo="newView"
               >
diff --git a/app/features/send/send-scanner.tsx b/app/features/send/send-scanner.tsx
index 34d328eed..bebe24775 100644
--- a/app/features/send/send-scanner.tsx
+++ b/app/features/send/send-scanner.tsx
@@ -6,6 +6,7 @@ import {
 } from '~/components/page';
 import { QRScanner } from '~/components/qr-scanner';
 import { useExchangeRate } from '~/hooks/use-exchange-rate';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { useToast } from '~/hooks/use-toast';
 import type { Money } from '~/lib/money';
 import { useNavigateWithViewTransition } from '~/lib/transitions/view-transition';
@@ -35,6 +36,7 @@ const useConverter = (sendAccount: Account) => {
 export default function SendScanner() {
   const { toast } = useToast();
   const navigate = useNavigateWithViewTransition();
+  const { buildTo } = useRedirectTo('/');
 
   const sendAccount = useSendStore((state) => state.getSourceAccount());
   const selectDestination = useSendStore((state) => state.selectDestination);
@@ -57,7 +59,7 @@ export default function SendScanner() {
 
     if (!amount) {
       // Navigate to send input to enter the amount
-      return navigate('/send', {
+      return navigate(buildTo('/send'), {
         applyTo: 'oldView',
         transition: 'slideDown',
       });
@@ -75,7 +77,7 @@ export default function SendScanner() {
       });
     }
 
-    navigate('/send/confirm', {
+    navigate(buildTo('/send/confirm'), {
       applyTo: 'newView',
       transition: 'slideUp',
     });
@@ -84,7 +86,11 @@ export default function SendScanner() {
   return (
     <>
       <PageHeader className="z-10">
-        <PageBackButton to="/send" transition="slideDown" applyTo="oldView" />
+        <PageBackButton
+          to={buildTo('/send')}
+          transition="slideDown"
+          applyTo="oldView"
+        />
         <PageHeaderTitle>Scan</PageHeaderTitle>
       </PageHeader>
       <PageContent className="relative flex items-center justify-center">
diff --git a/app/features/send/share-cashu-token.tsx b/app/features/send/share-cashu-token.tsx
index a1c999431..84fdb5115 100644
--- a/app/features/send/share-cashu-token.tsx
+++ b/app/features/send/share-cashu-token.tsx
@@ -20,6 +20,7 @@ import {
   CarouselItem,
 } from '~/components/ui/carousel';
 import useLocationData from '~/hooks/use-location';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { useToast } from '~/hooks/use-toast';
 import { canShare, shareContent } from '~/lib/share';
 import { LinkWithViewTransition } from '~/lib/transitions';
@@ -33,6 +34,7 @@ type Props = {
 export function ShareCashuToken({ token }: Props) {
   const { toast } = useToast();
   const { origin } = useLocationData();
+  const { redirectTo } = useRedirectTo('/');
   const [, copyToClipboard] = useCopyToClipboard();
   const amount = tokenToMoney(token);
   const [showOk, setShowOk] = useState(false);
@@ -45,7 +47,11 @@ export function ShareCashuToken({ token }: Props) {
   return (
     <Page>
       <PageHeader>
-        <ClosePageButton to="/" transition="slideDown" applyTo="oldView" />
+        <ClosePageButton
+          to={redirectTo}
+          transition="slideDown"
+          applyTo="oldView"
+        />
         <PageHeaderTitle>Send</PageHeaderTitle>
         {canShare() && (
           <PageHeaderItem position="right">
@@ -110,7 +116,7 @@ export function ShareCashuToken({ token }: Props) {
         <PageFooter className="pb-14">
           <Button asChild className="w-[80px]">
             <LinkWithViewTransition
-              to="/"
+              to={redirectTo}
               transition="slideDown"
               applyTo="oldView"
             >
diff --git a/app/features/transactions/transaction-details.tsx b/app/features/transactions/transaction-details.tsx
index 4de4d3ddf..0f3598f08 100644
--- a/app/features/transactions/transaction-details.tsx
+++ b/app/features/transactions/transaction-details.tsx
@@ -95,10 +95,10 @@ function getTransactionLabel(transaction: Transaction) {
 
 export function TransactionDetails({
   transaction,
-  defaultShowOkayButton = false,
+  redirectTo = '/',
 }: {
   transaction: Transaction;
-  defaultShowOkayButton?: boolean;
+  redirectTo?: string;
 }) {
   const account = useAccount(transaction.accountId);
   const { toast } = useToast();
@@ -133,7 +133,7 @@ export function TransactionDetails({
     isTransactionReversable(transaction) || isReclaimInProgress;
   const shouldShowOkButton =
     (didReclaimMutationSucceed && !isWaitingForStateUpdate) ||
-    (!shouldShowReclaimButton && defaultShowOkayButton);
+    !shouldShowReclaimButton;
 
   return (
     <>
@@ -207,7 +207,7 @@ export function TransactionDetails({
         <PageFooter className="pb-14">
           <Button asChild className="w-[80px]">
             <LinkWithViewTransition
-              to="/"
+              to={redirectTo}
               transition="slideDown"
               applyTo="oldView"
             >
diff --git a/app/hooks/use-redirect-to.ts b/app/hooks/use-redirect-to.ts
new file mode 100644
index 000000000..5fe24b507
--- /dev/null
+++ b/app/hooks/use-redirect-to.ts
@@ -0,0 +1,72 @@
+import { useSearchParams } from 'react-router';
+
+type PathWithSearch = { pathname: string; search: string };
+
+type UseRedirectToReturn = {
+  /** The final destination path (from URL param or default) */
+  redirectTo: string;
+  /**
+   * Creates a navigation target that preserves all current search params.
+   *
+   * Use this when navigating between steps in a flow to maintain the `redirectTo`
+   * param (and any other search params) throughout the entire flow.
+   *
+   * @param pathname - The path to navigate to
+   * @param extra - Additional search params to merge (will override existing keys)
+   *
+   * @example
+   * ```tsx
+   * // Current URL: /receive?redirectTo=/home&amount=100
+   * const to = buildTo('/receive/confirm', { step: '2' });
+   * // Result: { pathname: '/receive/confirm', search: 'redirectTo=/home&amount=100&step=2' }
+   * ```
+   */
+  buildTo: (pathname: string, extra?: Record<string, string>) => PathWithSearch;
+};
+
+/**
+ * Manages redirect URLs for multi-step flows (e.g., receive, send).
+ *
+ * Reads the `redirectTo` search param from the current URL to determine where
+ * to navigate after the flow completes. If not present, falls back to `defaultPath`.
+ *
+ * @param defaultPath - Fallback path when no `redirectTo` param exists (default: '/')
+ *
+ * @example
+ * ```tsx
+ * // URL: /receive?redirectTo=/transactions/123
+ * const { redirectTo, buildTo } = useRedirectTo('/');
+ *
+ * // After flow completes, navigate to the original page
+ * navigate(redirectTo); // navigates to '/transactions/123'
+ *
+ * // Navigate to next step while preserving redirectTo
+ * navigate(buildTo('/receive/confirm')); // '/receive/confirm?redirectTo=/transactions/123'
+ * ```
+ *
+ * @returns
+ * - `redirectTo` - The final destination path (from URL param or default)
+ * - `buildTo` - Helper to create navigation objects that preserve all search params
+ */
+export const useRedirectTo = (defaultPath = '/'): UseRedirectToReturn => {
+  const [searchParams] = useSearchParams();
+  const redirectTo = searchParams.get('redirectTo') ?? defaultPath;
+
+  const buildTo = (
+    pathname: string,
+    extra?: Record<string, string>,
+  ): PathWithSearch => {
+    const params = new URLSearchParams(searchParams);
+    if (extra) {
+      for (const [key, value] of Object.entries(extra)) {
+        params.set(key, value);
+      }
+    }
+    return {
+      pathname,
+      search: params.toString(),
+    };
+  };
+
+  return { redirectTo, buildTo };
+};
diff --git a/app/lib/transitions/view-transition.tsx b/app/lib/transitions/view-transition.tsx
index 8847b9744..5baeec8df 100644
--- a/app/lib/transitions/view-transition.tsx
+++ b/app/lib/transitions/view-transition.tsx
@@ -9,13 +9,13 @@ const transitions = [
   'slideDown',
   'fade',
 ] as const;
-type Transition = (typeof transitions)[number];
+export type Transition = (typeof transitions)[number];
 
 const isTransition = (value: unknown): value is Transition =>
   transitions.includes(value as Transition);
 
 const applyToTypes = ['newView', 'oldView', 'bothViews'] as const;
-type ApplyTo = (typeof applyToTypes)[number];
+export type ApplyTo = (typeof applyToTypes)[number];
 
 const isApplyTo = (value: unknown): value is ApplyTo =>
   applyToTypes.includes(value as ApplyTo);
diff --git a/app/routes/_protected.receive.cashu_.token.tsx b/app/routes/_protected.receive.cashu_.token.tsx
index 024a9ade7..4d2325af4 100644
--- a/app/routes/_protected.receive.cashu_.token.tsx
+++ b/app/routes/_protected.receive.cashu_.token.tsx
@@ -135,7 +135,8 @@ export async function clientLoader({ request }: Route.ClientLoaderArgs) {
         duration: 8000,
       });
     }
-    throw redirect('/');
+    const redirectTo = location.searchParams.get('redirectTo') ?? '/';
+    throw redirect(redirectTo);
   }
 
   return { token, selectedAccountId };
diff --git a/app/routes/_protected.receive.tsx b/app/routes/_protected.receive.tsx
index 7eb99e7f3..5d6ea195d 100644
--- a/app/routes/_protected.receive.tsx
+++ b/app/routes/_protected.receive.tsx
@@ -1,15 +1,107 @@
 import { Outlet, useSearchParams } from 'react-router';
 import { useAccountOrDefault } from '~/features/accounts/account-hooks';
 import { ReceiveProvider } from '~/features/receive';
+import {
+  type ReceiveFlowDefinition,
+  ReceiveFlowProvider,
+} from '~/features/receive/receive-flow';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
+import { useNavigateWithViewTransition } from '~/lib/transitions';
 
 export default function ReceiveLayout() {
   const [searchParams] = useSearchParams();
+  const navigate = useNavigateWithViewTransition();
+  const { redirectTo, buildTo } = useRedirectTo();
   const accountId = searchParams.get('accountId');
   const initialAccount = useAccountOrDefault(accountId);
 
+  const onSuccess = (transactionId: string) => {
+    navigate(
+      {
+        pathname: `/transactions/${transactionId}`,
+        search: `redirectTo=${encodeURIComponent(redirectTo)}`,
+      },
+      { transition: 'slideLeft', applyTo: 'newView' },
+    );
+  };
+
+  const flow: ReceiveFlowDefinition = {
+    amountInput: {
+      close: {
+        to: { pathname: redirectTo, search: '' },
+        transition: 'slideDown',
+        applyTo: 'oldView',
+      },
+      next: {
+        cashuLightningInvoice: {
+          to: buildTo('/receive/cashu'),
+          transition: 'slideLeft',
+          applyTo: 'newView',
+        },
+        sparkLightningInvoice: {
+          to: buildTo('/receive/spark'),
+          transition: 'slideLeft',
+          applyTo: 'newView',
+        },
+      },
+      actions: {
+        scanToken: {
+          to: buildTo('/receive/scan'),
+          transition: 'slideUp',
+          applyTo: 'newView',
+        },
+        claimCashuToken: (selectedAccountId) => ({
+          to: buildTo('/receive/cashu/token', { selectedAccountId }),
+          transition: 'slideLeft',
+          applyTo: 'newView',
+        }),
+      },
+    },
+    scanToken: {
+      back: {
+        to: buildTo('/receive'),
+        transition: 'slideDown',
+        applyTo: 'oldView',
+      },
+      next: {
+        claimCashuToken: (selectedAccountId) => ({
+          to: buildTo('/receive/cashu/token', { selectedAccountId }),
+          transition: 'slideLeft',
+          applyTo: 'newView',
+        }),
+      },
+    },
+    cashuLightningInvoice: {
+      back: {
+        to: buildTo('/receive'),
+        transition: 'slideRight',
+        applyTo: 'oldView',
+      },
+      onSuccess,
+    },
+    sparkLightningInvoice: {
+      back: {
+        to: buildTo('/receive'),
+        transition: 'slideDown',
+        applyTo: 'oldView',
+      },
+      onSuccess,
+    },
+    claimCashuToken: {
+      back: {
+        to: buildTo('/receive'),
+        transition: 'slideRight',
+        applyTo: 'oldView',
+      },
+      onSuccess,
+    },
+  };
+
   return (
     <ReceiveProvider initialAccount={initialAccount}>
-      <Outlet />
+      <ReceiveFlowProvider flow={flow}>
+        <Outlet />
+      </ReceiveFlowProvider>
     </ReceiveProvider>
   );
 }
diff --git a/app/routes/_protected.send.share.$swapId.tsx b/app/routes/_protected.send.share.$swapId.tsx
index a05b99b12..a45e8270a 100644
--- a/app/routes/_protected.send.share.$swapId.tsx
+++ b/app/routes/_protected.send.share.$swapId.tsx
@@ -13,22 +13,30 @@ import {
 } from '~/features/send/cashu-send-swap-hooks';
 import { ShareCashuToken } from '~/features/send/share-cashu-token';
 import { MoneyWithConvertedAmount } from '~/features/shared/money-with-converted-amount';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { getCashuProtocolUnit } from '~/lib/cashu';
 import { useNavigateWithViewTransition } from '~/lib/transitions';
 import type { Route } from './+types/_protected.send.share.$swapId';
 
 export default function SendShare({ params }: Route.ComponentProps) {
   const navigate = useNavigateWithViewTransition();
+  const { redirectTo } = useRedirectTo('/');
 
   const { data: swap } = useCashuSendSwap(params.swapId);
 
   useTrackCashuSendSwap({
     id: params.swapId,
     onCompleted: (swap) => {
-      navigate(`/transactions/${swap.transactionId}?redirectTo=/`, {
-        transition: 'fade',
-        applyTo: 'newView',
-      });
+      navigate(
+        {
+          pathname: `/transactions/${swap.transactionId}`,
+          search: `?redirectTo=${encodeURIComponent(redirectTo)}`,
+        },
+        {
+          transition: 'fade',
+          applyTo: 'newView',
+        },
+      );
     },
   });
 
@@ -38,7 +46,11 @@ export default function SendShare({ params }: Route.ComponentProps) {
     return (
       <Page>
         <PageHeader>
-          <ClosePageButton to="/" transition="slideDown" applyTo="oldView" />
+          <ClosePageButton
+            to={redirectTo}
+            transition="slideDown"
+            applyTo="oldView"
+          />
           <PageHeaderTitle>Send</PageHeaderTitle>
         </PageHeader>
         <PageContent className="animate-in items-center gap-0 overflow-x-hidden overflow-y-hidden duration-300">
diff --git a/app/routes/_protected.transactions.$transactionId_.tsx b/app/routes/_protected.transactions.$transactionId_.tsx
index 9c70818dc..bfd07a605 100644
--- a/app/routes/_protected.transactions.$transactionId_.tsx
+++ b/app/routes/_protected.transactions.$transactionId_.tsx
@@ -1,4 +1,3 @@
-import { useSearchParams } from 'react-router';
 import {
   ClosePageButton,
   Page,
@@ -7,20 +6,20 @@ import {
 } from '~/components/page';
 import { TransactionDetails } from '~/features/transactions/transaction-details';
 import { useTransaction } from '~/features/transactions/transaction-hooks';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import type { Route } from './+types/_protected.transactions.$transactionId_';
 
 export default function TransactionDetailsPage({
   params: { transactionId },
 }: Route.ComponentProps) {
   const { data: transaction } = useTransaction(transactionId);
-  const [searchParams] = useSearchParams();
-  const redirectTo = searchParams.get('redirectTo');
+  const { redirectTo } = useRedirectTo('/transactions');
 
   return (
     <Page>
       <PageHeader className="z-10">
         <ClosePageButton
-          to={redirectTo ?? '/transactions'}
+          to={redirectTo}
           transition="slideDown"
           applyTo="oldView"
         />
@@ -32,10 +31,7 @@ export default function TransactionDetailsPage({
               : 'Sent'}
         </PageHeaderTitle>
       </PageHeader>
-      <TransactionDetails
-        transaction={transaction}
-        defaultShowOkayButton={!!redirectTo}
-      />
+      <TransactionDetails transaction={transaction} redirectTo={redirectTo} />
     </Page>
   );
 }
diff --git a/app/routes/_public.mint-risks.tsx b/app/routes/_public.mint-risks.tsx
index 0840d3229..c2999a987 100644
--- a/app/routes/_public.mint-risks.tsx
+++ b/app/routes/_public.mint-risks.tsx
@@ -1,21 +1,18 @@
-import { useSearchParams } from 'react-router';
 import logo from '~/assets/full_logo.png';
 import mintRisksContent from '~/assets/mint-risks.md?raw';
 import { Markdown } from '~/components/markdown';
 import { ScrollArea } from '~/components/ui/scroll-area';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { LinkWithViewTransition } from '~/lib/transitions';
 
 export default function MintRisksPage() {
-  const [searchParams] = useSearchParams();
-  const redirectTo = searchParams.get('redirectTo');
+  const { redirectTo } = useRedirectTo('/');
 
   return (
     <ScrollArea className="mx-auto h-dvh max-w-4xl px-4 py-8" hideScrollbar>
       <header className="mb-8 flex items-center justify-start">
         <LinkWithViewTransition
-          to={{
-            pathname: redirectTo ?? '/',
-          }}
+          to={redirectTo}
           transition="slideDown"
           applyTo="oldView"
         >
diff --git a/app/routes/_public.privacy.tsx b/app/routes/_public.privacy.tsx
index 3ae706735..b0fae3d9d 100644
--- a/app/routes/_public.privacy.tsx
+++ b/app/routes/_public.privacy.tsx
@@ -1,20 +1,17 @@
-import { useSearchParams } from 'react-router';
 import logo from '~/assets/full_logo.png';
 import privacyContent from '~/assets/privacy-policy.md?raw';
 import { Markdown } from '~/components/markdown';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { LinkWithViewTransition } from '~/lib/transitions';
 
 export default function PrivacyPage() {
-  const [searchParams] = useSearchParams();
-  const redirectTo = searchParams.get('redirectTo');
+  const { redirectTo } = useRedirectTo('/');
 
   return (
     <div className="mx-auto h-dvh max-w-4xl overflow-y-auto overflow-x-hidden px-4 py-8 [-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
       <header className="mb-8 flex items-center justify-start">
         <LinkWithViewTransition
-          to={{
-            pathname: redirectTo ?? '/',
-          }}
+          to={redirectTo}
           transition="slideDown"
           applyTo="oldView"
         >
diff --git a/app/routes/_public.terms.tsx b/app/routes/_public.terms.tsx
index a1ca0ab72..770d18e22 100644
--- a/app/routes/_public.terms.tsx
+++ b/app/routes/_public.terms.tsx
@@ -1,20 +1,17 @@
-import { useSearchParams } from 'react-router';
 import logo from '~/assets/full_logo.png';
 import termsContent from '~/assets/terms-of-use.md?raw';
 import { Markdown } from '~/components/markdown';
+import { useRedirectTo } from '~/hooks/use-redirect-to';
 import { LinkWithViewTransition } from '~/lib/transitions';
 
 export default function TermsPage() {
-  const [searchParams] = useSearchParams();
-  const redirectTo = searchParams.get('redirectTo');
+  const { redirectTo } = useRedirectTo('/');
 
   return (
     <div className="mx-auto h-dvh max-w-4xl overflow-y-auto overflow-x-hidden px-4 py-8 [-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
       <header className="mb-8 flex items-center justify-start">
         <LinkWithViewTransition
-          to={{
-            pathname: redirectTo ?? '/',
-          }}
+          to={redirectTo}
           transition="slideDown"
           applyTo="oldView"
         >