diff --git a/src/app/api/pnl/route.ts b/src/app/api/pnl/route.ts
index d2a84d9..6290926 100644
--- a/src/app/api/pnl/route.ts
+++ b/src/app/api/pnl/route.ts
@@ -47,4 +47,7 @@ export async function GET() {
   return NextResponse.json(data);
 }
 
+<<<<<<< HEAD
+=======
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/app/api/upload/route.ts b/src/app/api/upload/route.ts
index e32a022..4fee8bd 100644
--- a/src/app/api/upload/route.ts
+++ b/src/app/api/upload/route.ts
@@ -28,4 +28,7 @@ export async function POST(request: NextRequest) {
   );
 }
 
+<<<<<<< HEAD
+=======
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/app/page.tsx b/src/app/page.tsx
index db906f5..d44e798 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -40,10 +40,19 @@ import Icon from "../components/ui/Icon";
  * Manages high-level state for wallet connection, active tabs, and invoice data.
  */
 export default function Page() {
+<<<<<<< HEAD
+  // --- Component State ---
+  /** The public Stellar address of the connected user */
+  const [address, setAddress] = useState("");
+  /** List of invoices fetched from the backend pipeline */
+  const [invoices, setInvoices] = useState([]);
+  /** Loading state for initial data fetch */
+=======
   const router = useRouter();
   const searchParams = useSearchParams();
   const { isConnected, walletAddress, isConnecting } = useWalletConnection();
   const [invoices, setInvoices] = useState<InvoiceSummary[]>([]);
+>>>>>>> upstream/main
   const [loading, setLoading] = useState(false);
   /** Controls visibility of the Invoice Minting modal */
   const [showMintForm, setShowMintForm] = useState(false);
@@ -56,6 +65,16 @@ export default function Page() {
   const { toggleWatchlist, isInWatchlist } = useWatchlist();
   const riskSocketRef = useRef<RiskSocketClient | null>(null);
 
+<<<<<<< HEAD
+  // --- Handlers ---
+
+  /**
+   * Triggers the Stellar wallet connection flow.
+   * Supports multiple providers via the stellar-wallets-kit.
+   * 
+   * @param {WalletType} walletType - The ID of the wallet provider (e.g., Freighter).
+   */
+=======
   // Initialize filters from URL params
   const [filters, setFilters] = useState<InvoiceFilters>(() => ({
     minApy: parseFloat(searchParams.get('minApy') || '0'),
@@ -77,11 +96,38 @@ export default function Page() {
 
   
   // 1. Connect Stellar Wallet (supports Freighter, Albedo, xBull)
+>>>>>>> upstream/main
   const handleConnectWallet = async (walletType: WalletType) => {
     try {
       const userInfo = await connectWallet(walletType);
       if (userInfo && userInfo.publicKey) {
         setAddress(userInfo.publicKey);
+<<<<<<< HEAD
+        console.log("[Dashboard] Wallet connected:", userInfo.publicKey, "Provider:", userInfo.walletType);
+      }
+    } catch (e: any) {
+      console.error("[Dashboard] Connection failed:", e.message);
+      // In production, this would be a user-friendly toast notification
+      alert(e.message || "Failed to connect to wallet.");
+    }
+  };
+
+  /**
+   * Fetches the latest verified assets from the RWA pipeline.
+   * Currently points to a local mock API for development.
+   */
+  const fetchInvoices = async () => {
+    setLoading(true);
+    try {
+      // TODO: Replace with environment-aware API base URL
+      const res = await fetch("http://localhost:3000/invoices");
+      const data = await res.json();
+      setInvoices(data);
+    } catch (e) {
+      console.warn("[Dashboard] Asset pipeline API not reachable. Check if local server is running.");
+    } finally {
+      setLoading(false);
+=======
         console.log("Wallet connected:", userInfo.publicKey, "Type:", userInfo.walletType);
         showSuccess("Wallet connected");
       }
@@ -89,6 +135,7 @@ export default function Page() {
       const error = e as Error;
       console.error("Connection failed:", error.message);
       showError(error.message || "Failed to connect to wallet.");
+>>>>>>> upstream/main
     }
   };
 
@@ -118,6 +165,24 @@ export default function Page() {
     };
   }, []);
 
+<<<<<<< HEAD
+  /**
+   * Debugging utility for testing transaction status notifications.
+   */
+  const handleTestToast = () => {
+    const toast = useTransactionToast();
+    toast.loading();
+    setTimeout(() => toast.success(), 2000);
+  };
+
+  /**
+   * Callback triggered when a new invoice is successfully submitted for minting.
+   * 
+   * @param {any} data - The validated invoice metadata.
+   */
+  const handleInvoiceMint = (data: any) => {
+    console.log("[Dashboard] Mint request received:", data);
+=======
   useEffect(() => {
     if (!walletAddress) {
       riskSocketRef.current?.disconnect();
@@ -163,6 +228,7 @@ export default function Page() {
 
   const handleInvoiceMint = (data: Record<string, unknown>) => {
     console.log("Invoice data received:", data);
+>>>>>>> upstream/main
     setShowMintForm(false);
     // TODO: Initiate Soroban contract call for minting the NFT
   };
@@ -172,7 +238,11 @@ export default function Page() {
   /** Tab definitions for the main navigation */
   const tabs = [
     { id: "dashboard", label: "Dashboard" },
+<<<<<<< HEAD
+    { id: "watchlist", label: "Watchlist", icon: <Star size={16} aria-hidden="true" /> },
+=======
     { id: "watchlist", label: "Watchlist", icon: <Icon icon={Star} dense /> },
+>>>>>>> upstream/main
   ];
 
 
diff --git a/src/components/AddTrustlineButton.tsx b/src/components/AddTrustlineButton.tsx
index 2337557..da2a8c9 100644
--- a/src/components/AddTrustlineButton.tsx
+++ b/src/components/AddTrustlineButton.tsx
@@ -1,42 +1,90 @@
+<<<<<<< HEAD
+/**
+ * Add Trustline Button Component.
+ * Encapsulates the logic for establishing a Stellar trustline for a specific asset.
+ * A trustline is mandatory before an account can hold non-native assets.
+ */
+
+import React, { useState } from "react";
+import { toast } from "react-hot-toast";
+import { Plus, Check, Loader2, ShieldCheck, AlertCircle } from "lucide-react";
+=======
 "use client";
 
 import React, { useState } from "react";
 import { Plus, Check, Loader2 } from "lucide-react";
+>>>>>>> upstream/main
 import { addTrustline } from "../lib/stellar";
 import { dismissToast, showError, showLoading, showSuccess } from "../lib/toast";
 import Button from "./ui/Button";
 import Icon from "./ui/Icon";
 
+/**
+ * Props for the AddTrustlineButton component.
+ */
 interface AddTrustlineButtonProps {
+  /** The 1-12 character asset code (e.g., "USDC") */
   assetCode: string;
+  /** The public Stellar address of the asset issuer */
   assetIssuer: string;
 }
 
 /**
- * A reusable button that establishes a Trustline for a specific Stellar asset
- * using the Freighter wallet extension.
+ * A specialized button that handles the 'change_trust' operation flow.
  */
 export default function AddTrustlineButton({ assetCode, assetIssuer }: AddTrustlineButtonProps) {
+  // --- Component State ---
+  /** Current status of the asynchronous trustline operation */
   const [status, setStatus] = useState<"idle" | "loading" | "success" | "error">("idle");
 
+  /**
+   * Initiates the trustline transaction flow.
+   */
   const handleAddTrustline = async () => {
+    // Prevent redundant clicks
     if (status === "loading" || status === "success") return;
 
     setStatus("loading");
+<<<<<<< HEAD
+    const toastId = toast.loading(`Establishing ${assetCode} trustline...`);
+=======
     const toastId = showLoading(`Requesting ${assetCode} trustline...`);
+>>>>>>> upstream/main
 
     try {
+      // 1. Trigger the Stellar SDK / Wallet transaction
       await addTrustline(assetCode, assetIssuer);
 
       setStatus("success");
+<<<<<<< HEAD
+      toast.success(`${assetCode} Trustline Active`, { 
+        id: toastId,
+        icon: '🛡️'
+      });
+      
+      // 2. Revert to idle after 5 seconds to reset UI
+=======
       dismissToast(toastId);
       showSuccess(`${assetCode} Trustline Established!`);
 
       // Revert to idle after 5 seconds
+>>>>>>> upstream/main
       setTimeout(() => setStatus("idle"), 5000);
+      console.log(`[AddTrustline] Successfully added ${assetCode} from ${assetIssuer}`);
     } catch (error: any) {
-      console.error(`[AddTrustline] Error:`, error);
+      console.error(`[AddTrustline] Failed to add ${assetCode}:`, error);
       setStatus("error");
+<<<<<<< HEAD
+      
+      // User-friendly error mapping
+      const errorMsg = error.message?.toLowerCase().includes("denied") 
+        ? "Transaction rejected by user" 
+        : `Network error adding ${assetCode}`;
+        
+      toast.error(errorMsg, { id: toastId });
+      
+      // 3. Revert to idle after a short delay to allow retry
+=======
 
       // Handle rejection vs generic error
       const errorMsg = error.message?.includes("denied")
@@ -47,6 +95,7 @@ export default function AddTrustlineButton({ assetCode, assetIssuer }: AddTrustl
       showError(errorMsg);
 
       // Revert to idle after 3 seconds to allow retry
+>>>>>>> upstream/main
       setTimeout(() => setStatus("idle"), 3000);
     }
   };
@@ -56,10 +105,32 @@ export default function AddTrustlineButton({ assetCode, assetIssuer }: AddTrustl
       variant="secondary"
       onClick={handleAddTrustline}
       disabled={status === "loading" || status === "success"}
+<<<<<<< HEAD
+      className={`flex items-center gap-2 text-[10px] font-black uppercase tracking-widest py-2 px-4 h-auto transition-all duration-300 border ${
+        status === "success" 
+          ? "bg-emerald-500/10 text-emerald-400 border-emerald-500/30" 
+          : "bg-slate-800/50 text-slate-400 border-slate-700 hover:border-slate-500 hover:text-white"
+      }`}
+      aria-label={`Add trustline for ${assetCode}`}
+=======
       className={`flex items-center gap-2 text-xs py-1.5 px-3 h-auto transition-all duration-200 ${status === "success" ? "bg-green-600/20 text-green-400 border-green-600/50" : ""
         }`}
+>>>>>>> upstream/main
     >
+      {/* Dynamic Icon State */}
       {status === "loading" ? (
+<<<<<<< HEAD
+        <Loader2 size={12} className="animate-spin text-blue-400" />
+      ) : status === "success" ? (
+        <ShieldCheck size={12} className="text-emerald-400" />
+      ) : status === "error" ? (
+        <AlertCircle size={12} className="text-rose-400" />
+      ) : (
+        <Plus size={12} className="group-hover:rotate-90 transition-transform" />
+      )}
+      
+      {/* Dynamic Label State */}
+=======
         <Icon icon={Loader2} dense className="animate-spin" />
       ) : status === "success" ? (
         <Icon icon={Check} dense />
@@ -67,13 +138,24 @@ export default function AddTrustlineButton({ assetCode, assetIssuer }: AddTrustl
         <Icon icon={Plus} dense />
       )}
 
+>>>>>>> upstream/main
       <span>
-        {status === "loading" ? "Signing..." : status === "success" ? "Trustline Active" : `Add ${assetCode}`}
+        {status === "loading" 
+          ? "Signing..." 
+          : status === "success" 
+            ? "Established" 
+            : status === "error"
+              ? "Retry"
+              : `Add ${assetCode}`
+        }
       </span>
     </Button>
   );
 }
 
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/Card.tsx b/src/components/Card.tsx
index de74564..c36714a 100644
--- a/src/components/Card.tsx
+++ b/src/components/Card.tsx
@@ -51,6 +51,9 @@ export default function Card({
     </div>
   );
 }
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/ConnectWallet.tsx b/src/components/ConnectWallet.tsx
index 7d99b6f..a7fe86b 100644
--- a/src/components/ConnectWallet.tsx
+++ b/src/components/ConnectWallet.tsx
@@ -1,24 +1,49 @@
+/**
+ * Connect Wallet Component.
+ * A standalone button/dropdown component for managing Stellar wallet sessions.
+ * Displays the connected address and provides a disconnect option.
+ */
+
 "use client";
+
 import { useState, useRef, useEffect } from "react";
-import { connectWallet, WalletType, FREIGHTER_ID } from "../lib/stellar";
+import { connectWallet, WalletType, FREIGHTER_ID, shortenAddress } from "../lib/stellar";
 import Button from "./ui/Button";
 import { useTokenStore } from "../stores/tokenStore";
+<<<<<<< HEAD
+import { LogOut, ChevronDown, User, ShieldCheck } from "lucide-react";
+=======
 import { useWalletConnection } from "../hooks/useWalletConnection";
 import { getCachedWalletConnection } from "../lib/walletCache";
 import { LogOut, ChevronDown } from "lucide-react";
 import WalletModal from "./WalletModal";
 import AuthenticatedSkeleton from "./AuthenticatedSkeleton";
 import Icon from "./ui/Icon";
+>>>>>>> upstream/main
 
+/** Key for purging recent token history on logout */
 const RECENT_TOKENS_KEY = "tradeflow_recent_tokens";
 
+/**
+ * A component that handles the wallet connection flow and account display.
+ */
 export default function ConnectWallet() {
+<<<<<<< HEAD
+      // --- Component State ---
+      const [pubKey, setPubKey] = useState<string | null>(null);
+=======
+>>>>>>> upstream/main
       const [isDropdownOpen, setIsDropdownOpen] = useState(false);
       const [isWalletModalOpen, setIsWalletModalOpen] = useState(false);
       const { setConnected } = useTokenStore();
       const { connectWallet, disconnectWallet, isInitialized, isRevalidating } = useWalletConnection();
       const dropdownRef = useRef<HTMLDivElement>(null);
 
+<<<<<<< HEAD
+      /**
+       * Effect: Closes the account dropdown when clicking outside.
+       */
+=======
       // Get cached state synchronously to prevent UI flicker
       const cached = getCachedWalletConnection();
       const [pubKey, setPubKey] = useState<string | null>(() => {
@@ -41,6 +66,7 @@ export default function ConnectWallet() {
       }, [isInitialized, setConnected]);
 
       // Close dropdown when clicking outside
+>>>>>>> upstream/main
       useEffect(() => {
             const handleClickOutside = (event: MouseEvent) => {
                   if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
@@ -51,27 +77,55 @@ export default function ConnectWallet() {
             return () => document.removeEventListener("mousedown", handleClickOutside);
       }, []);
 
+<<<<<<< HEAD
+      /**
+       * Initiates the wallet connection process.
+       * 
+       * @param {WalletType} walletType - The ID of the wallet provider.
+       */
+      const handleConnect = async (walletType: WalletType = FREIGHTER_ID) => {
+            try {
+                  const userInfo = await connectWallet(walletType);
+                  if (userInfo.publicKey) {
+                        setPubKey(userInfo.publicKey);
+                        setConnected(true, userInfo.publicKey);
+                        console.log(`[ConnectWallet] Session started for: ${userInfo.publicKey}`);
+                  }
+=======
       const handleConnect = async (walletType: WalletType) => {
             try {
                   await connectWallet(walletType);
                   // The hook will update the cache and state automatically
+>>>>>>> upstream/main
             } catch (e: any) {
-                  console.error("Connection error:", e);
+                  console.error("[ConnectWallet] Connection failed:", e);
+                  // TODO: Use a toast instead of native alert
                   alert(e.message || "Failed to connect to wallet!");
             }
       };
 
+<<<<<<< HEAD
+      /**
+       * Terminates the session and clears related data.
+       */
+=======
       const handleConnectClick = () => {
             setIsWalletModalOpen(true);
       };
 
+>>>>>>> upstream/main
       const handleDisconnect = () => {
             setPubKey(null);
             setConnected(false, undefined);
+            // Clear local history for privacy/security
             localStorage.removeItem(RECENT_TOKENS_KEY);
             setIsDropdownOpen(false);
+            console.log("[ConnectWallet] Session terminated.");
       };
 
+<<<<<<< HEAD
+      // 1. Authenticated UI (Dropdown)
+=======
       // Show skeleton if we have cached state but haven't finished initialization
       if (cached.isCached && cached.isConnected && !isInitialized) {
             return (
@@ -90,24 +144,51 @@ export default function ConnectWallet() {
             );
       }
 
+>>>>>>> upstream/main
       if (pubKey) {
             return (
                   <div className="relative" ref={dropdownRef}>
                         <button
                               onClick={() => setIsDropdownOpen((prev) => !prev)}
-                              className="flex items-center gap-2 px-4 py-2 rounded-lg bg-slate-800 hover:bg-slate-700 border border-slate-700 text-slate-200 text-sm font-medium transition-colors"
+                              className="flex items-center gap-2.5 px-4 py-2.5 rounded-xl bg-slate-800/80 hover:bg-slate-700/80 border border-slate-700 text-slate-200 text-sm font-bold transition-all shadow-sm active:scale-[0.98]"
+                              aria-haspopup="menu"
+                              aria-expanded={isDropdownOpen}
                         >
+<<<<<<< HEAD
+                              <div className="w-2 h-2 rounded-full bg-emerald-400 shadow-[0_0_8px_rgba(52,211,153,0.5)] shrink-0" />
+                              <span className="font-mono tracking-tight">{shortenAddress(pubKey, 4)}</span>
+                              <ChevronDown size={14} className={`text-slate-500 transition-transform duration-300 ${isDropdownOpen ? "rotate-180" : ""}`} />
+=======
                               <span className="w-2 h-2 rounded-full bg-green-400 shrink-0" />
                               {`${pubKey.slice(0, 4)}...${pubKey.slice(-4)}`}
                               <Icon icon={ChevronDown} dense className={`transition-transform ${isDropdownOpen ? "rotate-180" : ""}`} />
+>>>>>>> upstream/main
                         </button>
 
                         {isDropdownOpen && (
-                              <div className="absolute right-0 mt-2 w-48 rounded-lg bg-slate-800 border border-slate-700 shadow-xl z-50 overflow-hidden">
-                                    <div className="px-3 py-2 border-b border-slate-700">
-                                          <p className="text-xs text-slate-400 font-medium">Connected Wallet</p>
-                                          <p className="text-xs text-slate-300 font-mono truncate mt-0.5">{pubKey}</p>
+                              <div 
+                                    className="absolute right-0 mt-2 w-64 rounded-2xl bg-slate-800 border border-slate-700 shadow-2xl z-50 overflow-hidden animate-in fade-in slide-in-from-top-2 duration-200"
+                                    role="menu"
+                              >
+                                    <div className="px-4 py-4 border-b border-slate-700 bg-slate-900/50">
+                                          <div className="flex items-center gap-2 mb-1.5">
+                                                <ShieldCheck size={14} className="text-blue-400" />
+                                                <p className="text-[10px] text-slate-400 font-black uppercase tracking-widest">Verified Account</p>
+                                          </div>
+                                          <p className="text-xs text-slate-200 font-mono break-all leading-relaxed">{pubKey}</p>
+                                    </div>
+                                    <div className="p-1.5">
+                                          <button
+                                                onClick={handleDisconnect}
+                                                className="w-full flex items-center gap-3 px-3 py-2.5 text-sm font-bold text-rose-400 hover:bg-rose-500/10 rounded-xl transition-all group"
+                                                role="menuitem"
+                                          >
+                                                <LogOut size={16} className="group-hover:translate-x-0.5 transition-transform" />
+                                                Disconnect Wallet
+                                          </button>
                                     </div>
+<<<<<<< HEAD
+=======
                                     <button
                                           onClick={handleDisconnect}
                                           className="w-full flex items-center gap-2 px-3 py-2.5 text-sm text-slate-300 hover:bg-red-500/10 hover:text-red-400 transition-colors"
@@ -115,18 +196,26 @@ export default function ConnectWallet() {
                                           <Icon icon={LogOut} dense />
                                           Disconnect Wallet
                                     </button>
+>>>>>>> upstream/main
                               </div>
                         )}
                   </div>
             );
       }
 
+      // 2. Unauthenticated UI (CTA Button)
       return (
             <div>
                   <Button
+<<<<<<< HEAD
+                        onClick={() => handleConnect(FREIGHTER_ID)}
+                        className="bg-indigo-600 hover:bg-indigo-500 shadow-xl shadow-indigo-500/20 flex items-center gap-2 px-7 py-3 rounded-xl font-bold uppercase tracking-widest text-xs transition-all active:scale-95"
+=======
                         onClick={handleConnectClick}
                         className="bg-purple-600 hover:bg-purple-700 shadow-lg flex items-center gap-2 px-6 py-3"
+>>>>>>> upstream/main
                   >
+                        <User size={16} />
                         Connect Wallet
                   </Button>
                   <WalletModal
@@ -138,6 +227,9 @@ export default function ConnectWallet() {
       );
 }
 
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/InvoiceMintForm.tsx b/src/components/InvoiceMintForm.tsx
index 6b76dfc..15ec5d1 100644
--- a/src/components/InvoiceMintForm.tsx
+++ b/src/components/InvoiceMintForm.tsx
@@ -10,8 +10,12 @@ import React, { useState, useEffect } from "react";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { z } from "zod";
+<<<<<<< HEAD
+import { X, Upload, Calendar, DollarSign, FileText } from "lucide-react";
+=======
 import { X, Upload, Calendar, DollarSign, Building, FileText, Info } from "lucide-react";
 import { useSession } from "next-auth/react";
+>>>>>>> upstream/main
 import Button from "./ui/Button";
 import { useMintInvoice } from "@/hooks/useMintInvoice";
 import Icon from "./ui/Icon";
@@ -19,12 +23,21 @@ import Icon from "./ui/Icon";
 // Enhanced validation schema with sanitization
 const sanitizeString = (str: string) => str.trim().replace(/[<>"'&]/g, '');
 
+<<<<<<< HEAD
+/**
+ * Zod validation schema for the invoice minting form.
+ * Ensures data integrity before submission to the network.
+ */
+const invoiceSchema = z.object({
+  /** Total value of the invoice in USD */
+=======
 const invoiceSchema = z.object({
   debtorName: z
     .string()
     .min(2, "Debtor name must be at least 2 characters")
     .max(100, "Debtor name cannot exceed 100 characters")
     .transform(sanitizeString),
+>>>>>>> upstream/main
   amount: z
     .number()
     .min(0.01, "Amount must be greater than 0")
@@ -33,6 +46,28 @@ const invoiceSchema = z.object({
   dueDate: z
     .string()
     .min(1, "Due date is required")
+<<<<<<< HEAD
+    .refine(
+      (date) => {
+        const selectedDate = new Date(date);
+        const today = new Date();
+        today.setHours(0, 0, 0, 0);
+        return selectedDate > today;
+      },
+      "Due date must be in the future"
+    ),
+  /** PDF document containing the invoice details */
+  invoiceFile: z
+    .instanceof(File)
+    .refine(
+      (file) => file.type === "application/pdf",
+      "Only PDF files are allowed"
+    )
+    .refine(
+      (file) => file.size <= 5 * 1024 * 1024, // 5MB limit
+      "File size must be less than 5MB"
+    ),
+=======
     .refine((date) => {
       const selectedDate = new Date(date);
       const today = new Date();
@@ -49,6 +84,7 @@ const invoiceSchema = z.object({
     .url("Must be a valid URL")
     .optional()
     .or(z.literal("")),
+>>>>>>> upstream/main
 });
 
 /** TypeScript type inferred from the validation schema */
@@ -60,6 +96,18 @@ type InvoiceFormData = z.infer<typeof invoiceSchema>;
 interface InvoiceMintFormProps {
   /** Callback to trigger when the form is closed/cancelled */
   onClose: () => void;
+<<<<<<< HEAD
+  /** Callback triggered on successful form validation */
+  onSubmit: (data: InvoiceFormData) => void;
+}
+
+/**
+ * A modal form component for minting new invoice-backed NFTs.
+ */
+export default function InvoiceMintForm({ onClose, onSubmit }: InvoiceMintFormProps) {
+  // --- Component State ---
+  /** Stores the name of the uploaded file for UI display */
+=======
   onSuccess?: (txStatus: string) => void;
 }
 
@@ -70,6 +118,7 @@ interface FeeEstimate {
 }
 
 export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormProps) {
+>>>>>>> upstream/main
   const [filePreview, setFilePreview] = useState<string | null>(null);
   const [feeEstimate, setFeeEstimate] = useState<FeeEstimate>({
     networkFee: 0,
@@ -91,6 +140,9 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
     resolver: zodResolver(invoiceSchema),
   });
 
+<<<<<<< HEAD
+  // --- Handlers ---
+=======
   // Calculate fees whenever amount changes
   const watchedAmount = watch("amount");
   
@@ -116,6 +168,7 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
       });
     }
   }, [watchedAmount]);
+>>>>>>> upstream/main
 
   /**
    * Manually updates the file field in react-hook-form when a file is selected.
@@ -130,6 +183,18 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
     }
   };
 
+<<<<<<< HEAD
+  /**
+   * Internal submission handler that wraps the provided onSubmit callback.
+   * 
+   * @param {InvoiceFormData} data - The validated form data.
+   */
+  const onFormSubmit = (data: InvoiceFormData) => {
+    console.log("[InvoiceMintForm] Validated data received:", data);
+    onSubmit(data);
+    reset();
+    setFilePreview(null);
+=======
   // Format payload for Soroban smart contract
   const formatContractPayload = (data: InvoiceFormData) => {
     const publicKey = (session?.user as any)?.publicKey;
@@ -148,6 +213,7 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
         timestamp: Date.now()
       }
     };
+>>>>>>> upstream/main
   };
 
   const onFormSubmit = async (data: InvoiceFormData) => {
@@ -179,6 +245,55 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
   const busy = isSubmitting || minting;
 
   return (
+<<<<<<< HEAD
+    <div className="fixed inset-0 bg-black/70 backdrop-blur-sm flex items-center justify-center z-50 p-4" role="dialog" aria-modal="true" aria-labelledby="modal-title">
+      <div className="bg-slate-800 rounded-3xl border border-slate-700 w-full max-w-md shadow-2xl overflow-hidden animate-in fade-in zoom-in duration-200">
+        {/* Header */}
+        <div className="flex items-center justify-between p-6 border-b border-slate-700 bg-slate-800/50">
+          <div className="flex items-center gap-3">
+            <div className="p-2 bg-blue-500/10 rounded-xl text-blue-400">
+              <FileText size={20} />
+            </div>
+            <h2 id="modal-title" className="text-xl font-bold text-white tracking-tight">Mint Invoice NFT</h2>
+          </div>
+          <button
+            onClick={onClose}
+            className="p-2 text-slate-400 hover:text-white hover:bg-white/5 rounded-full transition-all"
+            aria-label="Close modal"
+          >
+            <X size={20} />
+          </button>
+        </div>
+
+        {/* Form Body */}
+        <form onSubmit={handleSubmit(onFormSubmit)} className="p-6 space-y-6">
+          {/* Amount Input */}
+          <div className="space-y-2">
+            <label className="flex items-center gap-2 text-sm font-semibold text-slate-300 ml-1">
+              <DollarSign size={14} className="text-emerald-400" />
+              Invoice Value (USD)
+            </label>
+            <div className="relative group">
+              <input
+                type="number"
+                step="0.01"
+                min="0"
+                placeholder="0.00"
+                {...register("amount", { valueAsNumber: true })}
+                className="w-full px-4 py-3.5 bg-slate-900/50 border border-slate-700 rounded-2xl text-white placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all group-hover:border-slate-600"
+              />
+            </div>
+            {errors.amount && (
+              <p className="px-1 text-xs font-medium text-rose-400 animate-in slide-in-from-top-1">{errors.amount.message}</p>
+            )}
+          </div>
+
+          {/* Due Date Input */}
+          <div className="space-y-2">
+            <label className="flex items-center gap-2 text-sm font-semibold text-slate-300 ml-1">
+              <Calendar size={14} className="text-blue-400" />
+              Payment Due Date
+=======
     <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50 p-4">
       <div className="bg-slate-800 rounded-2xl border border-slate-700 w-full max-w-md">
         <div className="flex items-center justify-between p-6 border-b border-slate-700">
@@ -229,12 +344,25 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
             <label className="block text-sm font-medium text-slate-300 mb-2">
               <Icon icon={Calendar} dense className="inline mr-1" />
               Due Date *
+>>>>>>> upstream/main
             </label>
             <input
               type="date"
               {...register("dueDate")}
               className="w-full px-4 py-3.5 bg-slate-900/50 border border-slate-700 rounded-2xl text-white placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all"
             />
+<<<<<<< HEAD
+            {errors.dueDate && (
+              <p className="px-1 text-xs font-medium text-rose-400 animate-in slide-in-from-top-1">{errors.dueDate.message}</p>
+            )}
+          </div>
+
+          {/* File Upload Area */}
+          <div className="space-y-2">
+            <label className="flex items-center gap-2 text-sm font-semibold text-slate-300 ml-1">
+              <Upload size={14} className="text-indigo-400" />
+              Verification Document (PDF)
+=======
             {errors.dueDate && <p className="mt-2 text-sm text-red-400">{errors.dueDate.message}</p>}
           </div>
 
@@ -243,6 +371,7 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
             <label className="block text-sm font-medium text-slate-300 mb-2">
               <Icon icon={Upload} dense className="inline mr-1" />
               Invoice Document (PDF)
+>>>>>>> upstream/main
             </label>
             <div className="relative">
               <input
@@ -261,6 +390,31 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
                   : "bg-slate-900/50 border-slate-700 hover:border-slate-600 hover:bg-slate-900/80"
                 }`}
               >
+<<<<<<< HEAD
+                <Upload size={24} className={`mb-2 ${filePreview ? "text-indigo-400" : "text-slate-500"}`} />
+                <span className="text-sm font-medium text-slate-300 text-center px-4">
+                  {filePreview || "Drop your PDF here or click to browse"}
+                </span>
+                {!filePreview && <span className="text-[10px] text-slate-500 mt-1 uppercase tracking-widest font-bold">Max size: 5MB</span>}
+              </label>
+            </div>
+            {errors.invoiceFile && (
+              <p id="file-error" className="px-1 text-xs font-medium text-rose-400 animate-in slide-in-from-top-1">{errors.invoiceFile.message}</p>
+            )}
+          </div>
+
+          {/* Action Button */}
+          <div className="pt-2">
+            <Button
+              type="submit"
+              disabled={isSubmitting}
+              className="w-full py-4 px-6 rounded-2xl text-sm font-bold uppercase tracking-widest shadow-xl shadow-blue-500/10 active:scale-[0.98] transition-transform"
+              isLoading={isSubmitting}
+            >
+              Mint Asset NFT
+            </Button>
+          </div>
+=======
                 <Icon icon={Upload} dense className="mr-2 text-slate-400" />
                 <span className="text-slate-300">{filePreview || "Choose PDF file"}</span>
               </label>
@@ -329,11 +483,16 @@ export default function InvoiceMintForm({ onClose, onSuccess }: InvoiceMintFormP
           >
             {busy ? "Submitting to Stellar..." : "Mint Invoice NFT"}
           </Button>
+>>>>>>> upstream/main
         </form>
       </div>
     </div>
   );
 }
+<<<<<<< HEAD
+
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/LoanTable.tsx b/src/components/LoanTable.tsx
index a3ac5b0..1172543 100644
--- a/src/components/LoanTable.tsx
+++ b/src/components/LoanTable.tsx
@@ -1,4 +1,12 @@
+<<<<<<< HEAD
+/**
+ * Loan Tracking Table Component.
+ * Displays a list of active and historical loans associated with the user's invoices.
+ * Includes interest calculation logic and repayment actions.
+ */
+=======
 "use client";
+>>>>>>> upstream/main
 
 import React from 'react';
 import { formatCurrency, formatDate } from '../lib/format';
@@ -35,10 +43,23 @@ const MOCK_LOANS: Loan[] = [
   { id: 'L-003', invoiceId: 'INV-7731', amountBorrowed: 3500, interestRate: 8, startDate: '2026-02-01T00:00:00Z', status: 'Repaid' },
 ];
 
+<<<<<<< HEAD
+/**
+ * Calculates the simple interest accrued based on time elapsed.
+ * Formula: (Principal * AnnualRate) * (DaysElapsed / 365)
+ * 
+ * @param {number} amount - Principal amount borrowed.
+ * @param {number} rate - Annual interest rate (percentage).
+ * @param {string} startDateStr - ISO string of the loan start date.
+ * @returns {string} Formatted interest amount as a string.
+ */
+const calculateInterest = (amount: number, rate: number, startDateStr: string) => {
+=======
 // --- Helper Functions ---
 
 // Calculates interest based on time elapsed: (Amount * Rate) * (DaysElapsed / 365)
 const calculateInterest = (amount: number, rate: number, startDateStr: string): number => {
+>>>>>>> upstream/main
   const start = new Date(startDateStr);
   const now = new Date();
   const diffTime = Math.abs(now.getTime() - start.getTime());
@@ -54,12 +75,21 @@ const calculateInterest = (amount: number, rate: number, startDateStr: string):
 const StatusBadge = ({ status }: { status: LoanStatus }) => {
   switch (status) {
     case 'Repaid':
+<<<<<<< HEAD
+      return <span className="px-2.5 py-1 text-xs font-semibold rounded-full bg-emerald-100 text-emerald-800 border border-emerald-200" aria-label={`Status: ${status}`}>Repaid</span>;
+    case 'Overdue':
+      return <span className="px-2.5 py-1 text-xs font-semibold rounded-full bg-rose-100 text-rose-800 border border-rose-200" aria-label={`Status: ${status}`}>Overdue</span>;
+    case 'Active':
+    default:
+      return <span className="px-2.5 py-1 text-xs font-semibold rounded-full bg-blue-100 text-blue-800 border border-blue-200" aria-label={`Status: ${status}`}>Active</span>;
+=======
       return <span className="px-2.5 py-1 text-xs font-medium rounded-full bg-green-500/20 text-green-400 border border-green-500/30">Repaid</span>;
     case 'Overdue':
       return <span className="px-2.5 py-1 text-xs font-medium rounded-full bg-red-500/20 text-red-400 border border-red-500/30">Overdue</span>;
     case 'Active':
     default:
       return <span className="px-2.5 py-1 text-xs font-medium rounded-full bg-blue-500/20 text-blue-400 border border-blue-500/30">Active</span>;
+>>>>>>> upstream/main
   }
 };
 
@@ -72,6 +102,23 @@ export default function LoanTable() {
    * @param {string} loanId - The ID of the loan to repay.
    */
   const handleRepay = (loanId: string) => {
+<<<<<<< HEAD
+    // TODO: Connect to the Soroban smart contract repayment method
+    console.log(`[LoanTable] Initiating repayment flow for: ${loanId}`);
+  };
+
+  return (
+    <div className="w-full overflow-hidden shadow-lg border border-slate-700/50 rounded-2xl bg-slate-900/50">
+      <div className="overflow-x-auto">
+        <table className="min-w-full text-sm text-left text-slate-300">
+          <thead className="text-xs text-slate-400 uppercase bg-slate-800/80 border-b border-slate-700">
+            <tr>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Invoice ID</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Principal Borrowed</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Interest Accrued</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider">Status</th>
+              <th scope="col" className="px-6 py-5 font-bold tracking-wider text-right">Actions</th>
+=======
     console.log(`Initiating repayment for loan: ${loanId}`);
   };
 
@@ -114,6 +161,7 @@ export default function LoanTable() {
                   Repay
                 </button>
               </td>
+>>>>>>> upstream/main
             </tr>
           </thead>
           <tbody className="divide-y divide-slate-800 bg-transparent">
@@ -156,6 +204,9 @@ export default function LoanTable() {
     </div>
   );
 }
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/Navbar.tsx b/src/components/Navbar.tsx
index 8fe2e60..139c731 100644
--- a/src/components/Navbar.tsx
+++ b/src/components/Navbar.tsx
@@ -9,8 +9,13 @@
 import React, { useState } from "react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
+<<<<<<< HEAD
+import { Wallet, Copy, Check, CreditCard, Menu, X } from "lucide-react";
+import toast from "react-hot-toast";
+=======
 import { Wallet, Copy, Check, CreditCard } from "lucide-react";
 import { showError, showSuccess } from "../lib/toast";
+>>>>>>> upstream/main
 
 // Core UI components and modals
 import NetworkSelector from "./NetworkSelector";
@@ -39,7 +44,12 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
   const [copied, setCopied] = useState(false);
   /** Controls visibility of the fiat purchase modal */
   const [isFiatModalOpen, setIsFiatModalOpen] = useState(false);
+<<<<<<< HEAD
+  /** Controls mobile menu visibility */
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+=======
   const [isDropdownOpen, setIsDropdownOpen] = useState(false);
+>>>>>>> upstream/main
 
   /**
    * Copies the connected wallet address to the system clipboard.
@@ -51,10 +61,24 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
         setCopied(true);
         setTimeout(() => setCopied(false), 2000);
 
+<<<<<<< HEAD
+        toast.success("Address copied to clipboard!", {
+          icon: '📋',
+          style: {
+            borderRadius: '12px',
+            background: '#1e293b',
+            color: '#fff',
+          },
+        });
+      } catch (err) {
+        console.error('[Navbar] Failed to copy address:', err);
+        toast.error("Failed to copy address");
+=======
         showSuccess("Address copied to clipboard!");
       } catch (err) {
         console.error('Failed to copy address:', err);
         showError("Failed to copy address");
+>>>>>>> upstream/main
       }
     }
   };
@@ -88,10 +112,18 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
               <Link
                 key={link.href}
                 href={link.href}
+<<<<<<< HEAD
+                className={`text-sm font-bold tracking-wide uppercase transition-all ${
+                  isActive
+                    ? "text-blue-400 border-b-2 border-blue-400 pb-1"
+                    : "text-slate-400 hover:text-white pb-1"
+                }`}
+=======
                 className={`text-sm font-medium transition-colors ${isActive
                     ? "text-cyan-400"
                     : "text-slate-400 hover:text-white"
                   }`}
+>>>>>>> upstream/main
               >
                 {link.name}
               </Link>
@@ -113,12 +145,31 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
           className="hidden md:flex items-center gap-2 bg-emerald-600/10 hover:bg-emerald-600 text-emerald-400 hover:text-white px-5 py-2.5 rounded-2xl transition-all font-bold text-sm border border-emerald-500/20"
           aria-label="Open fiat on-ramp"
         >
+<<<<<<< HEAD
+          <CreditCard size={18} />
+          <span>Buy Crypto</span>
+=======
           <Icon icon={CreditCard} />
           Buy Crypto
+>>>>>>> upstream/main
         </button>
 
         {/* Wallet Connection / Account Display */}
         {address ? (
+<<<<<<< HEAD
+          <div className="flex items-center gap-2 bg-slate-800 border border-slate-700 pl-4 pr-2 py-1.5 rounded-2xl group hover:border-blue-500/50 transition-all">
+            <div className="w-2 h-2 rounded-full bg-emerald-500 animate-pulse" />
+            <span className="text-xs font-mono text-slate-300 font-semibold tracking-tight">
+              {`${address.slice(0, 6)}...${address.slice(-4)}`}
+            </span>
+            <button
+              onClick={copyToClipboard}
+              className="p-2 text-slate-500 hover:text-blue-400 hover:bg-blue-500/10 rounded-xl transition-all"
+              title="Copy Stellar address"
+              aria-label="Copy address"
+            >
+              {copied ? <Check size={14} className="text-emerald-400" /> : <Copy size={14} />}
+=======
           <div className="relative">
           <div className="flex items-center gap-2 bg-blue-600 hover:bg-blue-700 px-6 py-2 rounded-full transition">
             <Icon icon={Wallet} />
@@ -152,6 +203,7 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
               ) : (
                 <Icon icon={Copy} dense className="text-white" />
               )}
+>>>>>>> upstream/main
             </button>
             
             {/* Wallet Dropdown */}
@@ -189,6 +241,9 @@ export default function Navbar({ address, onConnect }: NavbarProps) {
     </header>
   );
 }
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/NetworkSelector.tsx b/src/components/NetworkSelector.tsx
index 17e190b..99ccf7c 100644
--- a/src/components/NetworkSelector.tsx
+++ b/src/components/NetworkSelector.tsx
@@ -1,33 +1,62 @@
+/**
+ * Network Selector Component.
+ * Allows users to toggle between Stellar Mainnet and Testnet environments.
+ * Persists the selection in local state and notifies parent components of changes.
+ */
+
 "use client";
 
 import React, { useState, useRef, useEffect } from "react";
+<<<<<<< HEAD
+import { ChevronDown, AlertTriangle, Globe, FlaskConical } from "lucide-react";
+=======
 import { ChevronDown, AlertTriangle } from "lucide-react";
 import Icon from "./ui/Icon";
+>>>>>>> upstream/main
 
+/** Supported Stellar network types */
 export type Network = "mainnet" | "testnet";
 
+/**
+ * Props for the NetworkSelector component.
+ */
 interface NetworkSelectorProps {
+  /** Optional callback triggered when the network is changed */
   onNetworkChange?: (network: Network) => void;
 }
 
+/**
+ * A dropdown component for selecting the active Stellar network.
+ */
 export default function NetworkSelector({ onNetworkChange }: NetworkSelectorProps) {
+  // --- Component State ---
   const [selectedNetwork, setSelectedNetwork] = useState<Network>("mainnet");
   const [isOpen, setIsOpen] = useState(false);
   const dropdownRef = useRef<HTMLDivElement>(null);
 
+  /**
+   * Available network configurations.
+   */
   const networks = [
     {
       id: "mainnet" as Network,
       name: "Stellar Mainnet",
-      description: "Production network"
+      description: "Production assets",
+      icon: <Globe size={14} className="text-blue-400" />
     },
     {
       id: "testnet" as Network,
       name: "Stellar Testnet", 
-      description: "Development network"
+      description: "Development assets",
+      icon: <FlaskConical size={14} className="text-yellow-400" />
     }
   ];
 
+  // --- Handlers ---
+
+  /**
+   * Effect: Closes the dropdown when clicking outside the component.
+   */
   useEffect(() => {
     const handleClickOutside = (event: MouseEvent) => {
       if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
@@ -41,6 +70,11 @@ export default function NetworkSelector({ onNetworkChange }: NetworkSelectorProp
     };
   }, []);
 
+  /**
+   * Updates the selected network and propagates the change.
+   * 
+   * @param {Network} network - The new network ID.
+   */
   const handleNetworkSelect = (network: Network) => {
     setSelectedNetwork(network);
     setIsOpen(false);
@@ -53,65 +87,94 @@ export default function NetworkSelector({ onNetworkChange }: NetworkSelectorProp
 
   return (
     <div className="relative" ref={dropdownRef}>
-      {/* Selected Network Button */}
+      {/* Trigger Button */}
       <button
         onClick={() => setIsOpen(!isOpen)}
-        className="flex items-center gap-2 bg-slate-800 hover:bg-slate-700 border border-slate-600 rounded-lg px-4 py-2 transition-colors min-w-[160px] justify-between"
+        className="flex items-center gap-2 bg-slate-800/80 hover:bg-slate-700/80 border border-slate-700 rounded-xl px-4 py-2 transition-all min-w-[160px] justify-between shadow-sm active:scale-[0.98]"
+        aria-haspopup="listbox"
+        aria-expanded={isOpen}
+        aria-label="Select Stellar Network"
       >
         <div className="flex items-center gap-2">
-          {/* Stellar Logo */}
-          <div className="w-5 h-5 bg-gradient-to-br from-blue-500 to-purple-600 rounded-full flex items-center justify-center">
-            <div className="w-2 h-2 bg-white rounded-full"></div>
+          {/* Network-specific Icon */}
+          <div className="flex items-center justify-center w-6 h-6 rounded-lg bg-slate-900/50">
+            {selectedNetworkData?.icon}
           </div>
-          <span className="font-medium text-white text-sm">
+          <span className="font-bold text-white text-xs uppercase tracking-wider">
             {selectedNetworkData?.name.replace("Stellar ", "")}
           </span>
         </div>
+<<<<<<< HEAD
+        <ChevronDown 
+          size={14} 
+          className={`text-slate-500 transition-transform duration-300 ${isOpen ? "rotate-180" : ""}`}
+        />
+=======
         <Icon icon={ChevronDown} dense className={`text-slate-400 transition-transform ${isOpen ? "rotate-180" : ""}`} />
+>>>>>>> upstream/main
       </button>
 
       {/* Testnet Warning Badge */}
       {selectedNetwork === "testnet" && (
+<<<<<<< HEAD
+        <div 
+          className="absolute -top-2.5 -right-2 bg-yellow-500 text-slate-900 rounded-full px-2 py-0.5 text-[10px] font-black uppercase tracking-tighter flex items-center gap-1 shadow-lg shadow-yellow-500/20"
+          title="You are using the test network"
+        >
+          <AlertTriangle size={10} strokeWidth={3} />
+=======
         <div className="absolute -top-2 -right-2 bg-yellow-500 text-slate-900 rounded-full px-2 py-1 text-xs font-bold flex items-center gap-1">
           <Icon icon={AlertTriangle} dense />
+>>>>>>> upstream/main
           Testnet
         </div>
       )}
 
-      {/* Dropdown Menu */}
+      {/* Dropdown List */}
       {isOpen && (
-        <div className="absolute top-full right-0 mt-1 bg-slate-800 border border-slate-600 rounded-lg shadow-lg z-50 overflow-hidden min-w-[200px]">
-          {networks.map((network) => (
-            <button
-              key={network.id}
-              onClick={() => handleNetworkSelect(network.id)}
-              className={`w-full text-left px-4 py-3 transition-colors ${
-                network.id === selectedNetwork
-                  ? "bg-blue-600/20 text-blue-400"
-                  : "hover:bg-slate-700 text-white"
-              }`}
-            >
-              <div className="flex items-center gap-3">
-                {/* Stellar Logo */}
-                <div className="w-5 h-5 bg-gradient-to-br from-blue-500 to-purple-600 rounded-full flex items-center justify-center flex-shrink-0">
-                  <div className="w-2 h-2 bg-white rounded-full"></div>
+        <div 
+          className="absolute top-full right-0 mt-2 bg-slate-800 border border-slate-700 rounded-2xl shadow-2xl z-50 overflow-hidden min-w-[220px] animate-in fade-in slide-in-from-top-2 duration-200"
+          role="listbox"
+        >
+          <div className="p-2 space-y-1">
+            {networks.map((network) => (
+              <button
+                key={network.id}
+                onClick={() => handleNetworkSelect(network.id)}
+                className={`w-full text-left px-3 py-2.5 rounded-xl transition-all ${
+                  network.id === selectedNetwork
+                    ? "bg-blue-600/10 text-blue-400 border border-blue-500/20"
+                    : "hover:bg-white/5 text-slate-300 hover:text-white border border-transparent"
+                }`}
+                role="option"
+                aria-selected={network.id === selectedNetwork}
+              >
+                <div className="flex items-center gap-3">
+                  <div className={`w-8 h-8 rounded-lg flex items-center justify-center ${
+                    network.id === selectedNetwork ? "bg-blue-500/20" : "bg-slate-900/50"
+                  }`}>
+                    {network.icon}
+                  </div>
+                  <div className="flex-1">
+                    <div className="font-bold text-xs uppercase tracking-tight">{network.name}</div>
+                    <div className="text-[10px] text-slate-500 font-medium">{network.description}</div>
+                  </div>
+                  {network.id === selectedNetwork && (
+                    <div className="w-1.5 h-1.5 bg-blue-400 rounded-full shadow-[0_0_8px_rgba(96,165,250,0.5)]" />
+                  )}
                 </div>
-                <div className="flex-1">
-                  <div className="font-medium text-sm">{network.name}</div>
-                  <div className="text-xs text-slate-400">{network.description}</div>
-                </div>
-                {network.id === selectedNetwork && (
-                  <div className="w-2 h-2 bg-blue-400 rounded-full"></div>
-                )}
-              </div>
-            </button>
-          ))}
+              </button>
+            ))}
+          </div>
         </div>
       )}
     </div>
   );
 }
 
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/SwapInterface.tsx b/src/components/SwapInterface.tsx
index 4769d92..07bfaac 100644
--- a/src/components/SwapInterface.tsx
+++ b/src/components/SwapInterface.tsx
@@ -1,3 +1,15 @@
+<<<<<<< HEAD
+/**
+ * Swap Interface Component.
+ * Provides a decentralized exchange (DEX) style interface for swapping 
+ * Stellar assets. Includes slippage control, price impact estimation, 
+ * and transaction status monitoring.
+ */
+
+"use client";
+
+=======
+>>>>>>> upstream/main
 import React, { useState, useEffect } from "react";
 import { ArrowUpDown, Settings, BarChart3, LineChart, TrendingUp } from "lucide-react";
 import TokenDropdown from "./TokenDropdown";
@@ -19,9 +31,96 @@ export default function SwapInterface() {
   
   // --- UI Visibility State ---
   const [isSettingsOpen, setIsSettingsOpen] = useState(false);
+<<<<<<< HEAD
+  const [isHighSlippageWarningOpen, setIsHighSlippageWarningOpen] = useState(false);
+  const [isTradeReviewOpen, setIsTradeReviewOpen] = useState(false);
+  const [isTransactionSignatureOpen, setIsTransactionSignatureOpen] = useState(false);
+  /** Visibility for the post-trade growth/share modal */
+  const [isSuccessModalOpen, setIsSuccessModalOpen] = useState(false);
+
+  // --- Trade Value State ---
+  const [fromAmount, setFromAmount] = useState("");
+  const [toAmount, setToAmount] = useState("");
+  /** Estimated price impact as a percentage */
+  const [priceImpact, setPriceImpact] = useState(0);
+  /** Mock balance for the selected source token */
+  const [fromBalance] = useState("1240.50");
+
+  // --- Submission & Timing State ---
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submissionStartTime, setSubmissionStartTime] = useState<number | null>(null);
+  const [timeLeft, setTimeLeft] = useState<string>("");
+
+  // --- Context Hooks ---
+  const { slippageTolerance, transactionDeadline } = useSlippage();
+
+  /**
+   * Countdown timer effect for transaction expiry.
+   * Runs when a transaction is pending submission.
+   */
+  useEffect(() => {
+    let interval: any;
+    if (isSubmitting && submissionStartTime) {
+      interval = setInterval(() => {
+        const now = Date.now();
+        const elapsed = Math.floor((now - submissionStartTime) / 1000);
+        const totalSeconds = transactionDeadline * 60;
+        const remaining = totalSeconds - elapsed;
+
+        if (remaining <= 0) {
+          clearInterval(interval);
+          setIsSubmitting(false);
+          setIsTransactionSignatureOpen(false);
+          setIsTradeReviewOpen(false);
+          setSubmissionStartTime(null);
+          toast.error("Transaction Expired", { duration: 5000 });
+        } else {
+          const minutes = Math.floor(remaining / 60);
+          const seconds = remaining % 60;
+          setTimeLeft(`${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`);
+        }
+      }, 1000);
+    }
+    return () => clearInterval(interval);
+  }, [isSubmitting, submissionStartTime, transactionDeadline]);
+
+  /**
+   * Persists token selections across page reloads.
+   */
+  useEffect(() => {
+    const savedFromToken = localStorage.getItem('tradeflow-fromToken');
+    const savedToToken = localStorage.getItem('tradeflow-toToken');
+
+    if (savedFromToken) setFromToken(savedFromToken);
+    if (savedToToken) setToToken(savedToToken);
+  }, []);
+
+  useEffect(() => {
+    localStorage.setItem('tradeflow-fromToken', fromToken);
+  }, [fromToken]);
+
+  useEffect(() => {
+    localStorage.setItem('tradeflow-toToken', toToken);
+  }, [toToken]);
+
+  /**
+   * Estimates the price impact based on the input amount.
+   * This is a simplified mock for development purposes.
+   * 
+   * @param {string} amount - The numeric amount string.
+   * @returns {number} The calculated percentage impact.
+   */
+  const calculatePriceImpact = (amount: string) => {
+    if (!amount || parseFloat(amount) <= 0) return 0;
+    const baseImpact = Math.min(parseFloat(amount) * 0.01, 15);
+    const tokenMultiplier = fromToken === "XLM" ? 1.2 : 1.0;
+    return baseImpact * tokenMultiplier;
+  };
+=======
   const [isProMode, setIsProMode] = useState(false);
 
   const { deadline } = useSettings();
+>>>>>>> upstream/main
 
   /**
    * Swaps the 'from' and 'to' tokens and their amounts.
@@ -62,7 +161,11 @@ export default function SwapInterface() {
       return;
     }
 
+<<<<<<< HEAD
+    const loadingToast = toast.loading("Processing swap calculation...");
+=======
     const loadingToast = showLoading("Processing swap...");
+>>>>>>> upstream/main
 
     try {
       // Threshold check for high slippage warning
@@ -75,13 +178,21 @@ export default function SwapInterface() {
       // Simulate network delay
       await new Promise((resolve) => setTimeout(resolve, 1500));
 
+<<<<<<< HEAD
+      toast.success(`Trade calculated: ${fromAmount} ${fromToken} → ${toAmount} ${toToken}`, {
+=======
       showSuccess(`Swapped ${fromAmount} ${fromToken} → ${toAmount} ${toToken}`, {
+>>>>>>> upstream/main
         id: loadingToast,
       });
 
       setIsTradeReviewOpen(true);
     } catch (error) {
+<<<<<<< HEAD
+      toast.error("Failed to calculate trade parameters", {
+=======
       showError("Failed to process swap", {
+>>>>>>> upstream/main
         id: loadingToast,
       });
     }
@@ -105,7 +216,11 @@ export default function SwapInterface() {
 
       setIsTransactionSignatureOpen(true);
     } catch (error) {
+<<<<<<< HEAD
+      toast.error("Failed to prepare transaction");
+=======
       showError("Failed to submit trade");
+>>>>>>> upstream/main
       setIsSubmitting(false);
       setSubmissionStartTime(null);
     }
@@ -138,8 +253,13 @@ export default function SwapInterface() {
   const handleTransactionSuccess = (signedXDR: string) => {
     console.log("[SwapInterface] Transaction signed:", signedXDR);
 
+<<<<<<< HEAD
+    toast.success("Trade executed successfully!", {
+      icon: "🚀",
+=======
     showSuccess("Transaction signed successfully!", {
       icon: "✅",
+>>>>>>> upstream/main
     });
 
     setIsTransactionSignatureOpen(false);
diff --git a/src/components/WalletModal.tsx b/src/components/WalletModal.tsx
index b0a76c1..1e3280b 100644
--- a/src/components/WalletModal.tsx
+++ b/src/components/WalletModal.tsx
@@ -1,27 +1,76 @@
+<<<<<<< HEAD
+/**
+ * Wallet Modal Component.
+ * Displays a selection of supported Stellar wallet providers (Freighter, xBull, Albedo).
+ * Provides information about each wallet and handles the selection callback.
+ */
+
+import React from "react";
+import { FREIGHTER_ID, XBULL_ID, ALBEDO_ID, WalletType } from "../lib/stellar";
+import { X, Info, Shield, Smartphone, Globe } from "lucide-react";
+=======
 "use client";
 
 import React from "react";
 import { FREIGHTER_ID, XBULL_ID, ALBEDO_ID, WalletType } from "../lib/stellar";
 import { getWalletDisplayName, getWalletDescription, getWalletIcon, getWalletBgColor } from "../lib/walletConnector";
 import { CloseIcon } from "./icons";
+>>>>>>> upstream/main
 
+/**
+ * Props for the WalletModal component.
+ */
 interface WalletModalProps {
+  /** Visibility toggle for the modal */
   isOpen: boolean;
+  /** Callback to close the modal */
   onClose: () => void;
+  /** Callback triggered when a wallet provider is selected */
   onConnect?: (walletType: WalletType) => void;
 }
 
+/**
+ * Internal representation of a wallet provider option.
+ */
 interface WalletOption {
+  /** The internal ID used by the stellar-wallets-kit */
   id: WalletType;
+  /** Human-readable name of the wallet */
   name: string;
+  /** Short description of the wallet's features */
   description: string;
-  icon: string;
+  /** Lucide icon component to represent the wallet type */
+  icon: React.ReactNode;
+  /** Tailwind background color class for the icon container */
   bgColor: string;
 }
 
+/**
+ * Supported wallet providers configuration.
+ */
 const walletOptions: WalletOption[] = [
   {
     id: FREIGHTER_ID,
+<<<<<<< HEAD
+    name: "Freighter",
+    description: "Secure browser extension wallet by Stellar Development Foundation.",
+    icon: <Shield size={20} />,
+    bgColor: "bg-blue-500"
+  },
+  {
+    id: XBULL_ID,
+    name: "xBull",
+    description: "Mobile-first and multi-platform Stellar wallet with advanced features.",
+    icon: <Smartphone size={20} />,
+    bgColor: "bg-orange-500"
+  },
+  {
+    id: ALBEDO_ID,
+    name: "Albedo",
+    description: "Convenient web-based wallet for seamless Stellar network access.",
+    icon: <Globe size={20} />,
+    bgColor: "bg-purple-500"
+=======
     name: getWalletDisplayName(FREIGHTER_ID),
     description: getWalletDescription(FREIGHTER_ID),
     icon: getWalletIcon(FREIGHTER_ID),
@@ -40,53 +89,80 @@ const walletOptions: WalletOption[] = [
     description: getWalletDescription(ALBEDO_ID),
     icon: getWalletIcon(ALBEDO_ID),
     bgColor: getWalletBgColor(ALBEDO_ID)
+>>>>>>> upstream/main
   }
 ];
 
+/**
+ * A modal overlay for selecting a wallet provider.
+ */
 export default function WalletModal({ isOpen, onClose, onConnect }: WalletModalProps) {
+  // 1. Conditional Rendering for Visibility
   if (!isOpen) return null;
 
+  /**
+   * Selection handler: closes the modal and triggers the connection flow.
+   * @param {WalletType} walletType - The ID of the chosen wallet.
+   */
   const handleWalletSelect = (walletType: WalletType) => {
     if (onConnect) onConnect(walletType);
     onClose();
   };
 
   return (
-    <div className="fixed inset-0 bg-black/50 backdrop-blur-sm z-50 flex items-center justify-center p-4">
-      <div className="bg-slate-800 rounded-2xl border border-slate-700 p-6 max-w-md w-full">
-        <div className="flex justify-between items-center mb-6">
-          <h2 className="text-xl font-semibold text-white">Connect Wallet</h2>
+    <div 
+      className="fixed inset-0 bg-black/70 backdrop-blur-md z-50 flex items-center justify-center p-4 animate-in fade-in duration-300"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="modal-title"
+    >
+      <div className="bg-slate-800 rounded-3xl border border-slate-700 p-1 max-w-md w-full shadow-2xl overflow-hidden animate-in zoom-in duration-200">
+        {/* Header Section */}
+        <div className="flex justify-between items-center p-6 bg-slate-800/50">
+          <div className="flex items-center gap-3">
+            <div className="p-2 bg-blue-500/10 rounded-xl text-blue-400">
+              <Shield size={20} />
+            </div>
+            <h2 id="modal-title" className="text-xl font-bold text-white tracking-tight">Connect Wallet</h2>
+          </div>
           <button
             onClick={onClose}
-            className="text-slate-400 hover:text-white transition-colors"
+            className="p-2 text-slate-400 hover:text-white hover:bg-white/5 rounded-full transition-all"
+            aria-label="Close modal"
           >
+<<<<<<< HEAD
+            <X size={20} />
+=======
             <CloseIcon />
+>>>>>>> upstream/main
           </button>
         </div>
 
-        <div className="space-y-3">
+        {/* Options List */}
+        <div className="p-6 space-y-3">
+          <p className="text-xs font-black text-slate-500 uppercase tracking-widest mb-4 ml-1">Select Provider</p>
           {walletOptions.map((wallet) => (
             <button
               key={wallet.id}
-              className="w-full bg-slate-700 hover:bg-slate-600 border border-slate-600 rounded-lg p-4 flex items-center gap-3 transition-colors"
+              className="w-full bg-slate-900/40 hover:bg-slate-700/60 border border-slate-700/50 hover:border-blue-500/30 rounded-2xl p-4 flex items-center gap-4 transition-all group active:scale-[0.98]"
               onClick={() => handleWalletSelect(wallet.id)}
             >
-              <div className={`w-10 h-10 ${wallet.bgColor} rounded-lg flex items-center justify-center`}>
-                <svg className="w-6 h-6 text-white" fill="currentColor" viewBox="0 0 24 24">
-                  <path d={wallet.icon}/>
-                </svg>
+              <div className={`w-12 h-12 ${wallet.bgColor} rounded-xl flex items-center justify-center text-white shadow-lg shadow-black/20 group-hover:scale-110 transition-transform`}>
+                {wallet.icon}
               </div>
               <div className="text-left">
-                <div className="font-medium text-white">{wallet.name}</div>
-                <div className="text-sm text-slate-400">{wallet.description}</div>
+                <div className="font-bold text-white tracking-tight">{wallet.name}</div>
+                <div className="text-xs text-slate-400 leading-relaxed mt-0.5">{wallet.description}</div>
               </div>
             </button>
           ))}
         </div>
 
-        <div className="mt-6 p-4 bg-slate-900/50 rounded-lg">
-          <p className="text-sm text-slate-400">
-            By connecting a wallet, you agree to the Terms of Service and Privacy Policy
+        {/* Footer/Disclosure */}
+        <div className="px-6 py-5 bg-slate-900/50 flex gap-3 items-start border-t border-slate-700/50">
+          <Info size={16} className="text-blue-400 shrink-0 mt-0.5" />
+          <p className="text-[11px] text-slate-400 leading-relaxed font-medium">
+            By connecting a wallet, you agree to our <span className="text-blue-400 hover:underline cursor-pointer">Terms of Service</span> and acknowledge you have read our <span className="text-blue-400 hover:underline cursor-pointer">Privacy Policy</span>.
           </p>
         </div>
       </div>
@@ -94,6 +170,9 @@ export default function WalletModal({ isOpen, onClose, onConnect }: WalletModalP
   );
 }
 
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/layout/Footer.tsx b/src/components/layout/Footer.tsx
index fc0a5a3..f36a37c 100644
--- a/src/components/layout/Footer.tsx
+++ b/src/components/layout/Footer.tsx
@@ -1,3 +1,8 @@
+/**
+ * Shared Footer Component.
+ * Contains copyright information, primary resource links, and social media integrations.
+ * Automatically sticks to the bottom of the viewport via flexbox in the layout.
+ */
 "use client";
 
 import React from "react";
@@ -5,10 +10,16 @@ import { ExternalLink } from "lucide-react";
 import NetworkToggle from "../NetworkToggle";
 import Icon from "../ui/Icon";
 
+import React from "react";
+import { ExternalLink, Twitter, Github, Mail } from "lucide-react";
+import Link from "next/link";
+
 /**
  * A consistent footer for all TradeFlow pages.
  */
 export default function Footer() {
+  // --- Configuration ---
+  const currentYear = new Date().getFullYear();
   const handleClearCache = () => {
     localStorage.clear();
     sessionStorage.clear(); // Good measure for QA
@@ -18,6 +29,92 @@ export default function Footer() {
   return (
     <footer className="bg-slate-900 border-t border-slate-800 py-12 px-8 mt-auto" role="contentinfo">
       <div className="max-w-7xl mx-auto">
+        <div className="flex flex-col lg:flex-row justify-between items-start lg:items-center gap-12 lg:gap-8">
+          
+          {/* Brand Info */}
+          <div className="space-y-4 max-w-sm">
+            <div className="flex items-center gap-2">
+              <div className="w-8 h-8 bg-blue-600 rounded-lg flex items-center justify-center">
+                <span className="text-white font-black text-sm">T</span>
+              </div>
+              <span className="text-lg font-black tracking-tight text-white uppercase">TradeFlow</span>
+            </div>
+            <p className="text-slate-500 text-sm leading-relaxed">
+              The premier dashboard for managing Real World Asset (RWA) backed invoices on the Stellar network.
+            </p>
+          </div>
+
+          {/* Navigation & Links */}
+          <div className="grid grid-cols-2 sm:grid-cols-3 gap-12 w-full lg:w-auto">
+            
+            {/* Resources Column */}
+            <div className="space-y-4">
+              <h4 className="text-xs font-bold text-slate-400 uppercase tracking-widest">Resources</h4>
+              <nav className="flex flex-col gap-3">
+                <a
+                  href="https://docs.tradeflow.example"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium inline-flex items-center gap-1"
+                >
+                  Documentation
+                  <ExternalLink size={12} className="opacity-50" />
+                </a>
+                <Link href="/faq" className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium">
+                  Help Center
+                </Link>
+              </nav>
+            </div>
+
+            {/* Legal Column */}
+            <div className="space-y-4">
+              <h4 className="text-xs font-bold text-slate-400 uppercase tracking-widest">Legal</h4>
+              <nav className="flex flex-col gap-3">
+                <Link href="/legal/terms" className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium">
+                  Terms of Service
+                </Link>
+                <Link href="/legal/privacy" className="text-slate-500 hover:text-blue-400 transition-colors text-sm font-medium">
+                  Privacy Policy
+                </Link>
+              </nav>
+            </div>
+
+            {/* Social Column */}
+            <div className="space-y-4">
+              <h4 className="text-xs font-bold text-slate-400 uppercase tracking-widest">Connect</h4>
+              <div className="flex gap-4">
+                <a
+                  href="https://twitter.com"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="p-2 bg-slate-800 rounded-xl text-slate-400 hover:text-blue-400 hover:bg-blue-400/10 transition-all"
+                  aria-label="Follow us on Twitter"
+                >
+                  <Twitter size={18} />
+                </a>
+                <a
+                  href="https://github.com"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="p-2 bg-slate-800 rounded-xl text-slate-400 hover:text-white hover:bg-white/10 transition-all"
+                  aria-label="View source on GitHub"
+                >
+                  <Github size={18} />
+                </a>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Bottom Bar */}
+        <div className="mt-12 pt-8 border-t border-slate-800/50 flex flex-col sm:flex-row justify-between items-center gap-4 text-center sm:text-left">
+          <div className="text-slate-600 text-[10px] font-bold uppercase tracking-tighter">
+            © {currentYear} TradeFlow Protocol. Built on Stellar.
+          </div>
+          <div className="flex items-center gap-1 text-[10px] font-bold text-slate-600 uppercase tracking-tighter">
+            <div className="w-1.5 h-1.5 rounded-full bg-emerald-500 shadow-[0_0_8px_rgba(16,185,129,0.5)]" />
+            Network Status: Operational
+          </div>
         <div className="flex flex-col md:flex-row justify-between items-center gap-4">
 
           <div className="flex items-center gap-4">
@@ -79,6 +176,7 @@ export default function Footer() {
     </footer>
   );
 }
+
 // Inconsequential change for repo health
 
 // Maintenance: minor update
diff --git a/src/components/ui/Button.tsx b/src/components/ui/Button.tsx
index 1de400b..aede98e 100644
--- a/src/components/ui/Button.tsx
+++ b/src/components/ui/Button.tsx
@@ -1,3 +1,74 @@
+<<<<<<< HEAD
+/**
+ * Shared Button component for the TradeFlow UI.
+ * Provides consistent styling, variants, and built-in accessibility.
+ */
+
+import React from "react";
+
+/**
+ * Props for the Button component.
+ * Extends standard HTML button attributes for full compatibility.
+ */
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** The content to be displayed inside the button */
+  children: React.ReactNode;
+  /** Visual style variant of the button */
+  variant?: "primary" | "secondary" | "outline" | "ghost";
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Optional loading state to disable button and show feedback */
+  isLoading?: boolean;
+}
+
+/**
+ * A versatile button component that supports different visual styles and states.
+ */
+export default function Button({
+  children,
+  variant = "primary",
+  className = "",
+  isLoading = false,
+  disabled,
+  ...props
+}: ButtonProps) {
+  // Core styling for all button types
+  const baseStyles = "px-4 py-2 font-medium rounded-lg transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-offset-tradeflow-dark disabled:opacity-50 disabled:cursor-not-allowed active:scale-[0.98]";
+
+  // Style definitions for each variant
+  const variantStyles = {
+    primary: "bg-tradeflow-accent hover:bg-tradeflow-accent/90 text-white focus:ring-tradeflow-accent",
+    secondary: "bg-slate-700 hover:bg-slate-600 text-white focus:ring-slate-500",
+    outline: "border-2 border-tradeflow-muted hover:border-tradeflow-accent hover:text-tradeflow-accent text-white",
+    ghost: "hover:bg-white/5 text-tradeflow-muted hover:text-white"
+  };
+
+  // Merge all styles into a single string
+  const combinedClassName = `${baseStyles} ${variantStyles[variant as keyof typeof variantStyles]} ${className}`;
+
+  return (
+    <button
+      className={combinedClassName}
+      disabled={disabled || isLoading}
+      // ARIA attributes for accessibility
+      aria-busy={isLoading}
+      aria-live="polite"
+      {...props}
+    >
+      {isLoading ? (
+        <span className="flex items-center justify-center gap-2">
+          <svg className="animate-spin h-4 w-4 text-current" viewBox="0 0 24 24">
+            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
+            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+          </svg>
+          Loading...
+        </span>
+      ) : children}
+    </button>
+  );
+}
+
+=======
 import React, { forwardRef } from "react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { twMerge } from "tailwind-merge";
@@ -61,3 +132,4 @@ export default Button;
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/ui/NetworkFeeIndicator.tsx b/src/components/ui/NetworkFeeIndicator.tsx
index e90cead..7a36fca 100644
--- a/src/components/ui/NetworkFeeIndicator.tsx
+++ b/src/components/ui/NetworkFeeIndicator.tsx
@@ -90,8 +90,16 @@ export default function NetworkFeeIndicator() {
   // 1. Loading State UI
   if (loading && !feeData) {
     return (
+<<<<<<< HEAD
+      <div 
+        className="flex items-center gap-1.5 text-xs text-slate-400"
+        aria-label="Loading network fee"
+      >
+        <Fuel size={16} />
+=======
       <div className="flex items-center gap-1.5 text-xs text-slate-400">
         <Icon icon={Fuel} dense />
+>>>>>>> upstream/main
         <span>Loading fee...</span>
       </div>
     );
@@ -100,8 +108,16 @@ export default function NetworkFeeIndicator() {
   // 2. Error/Fallback State UI
   if (error || !feeData) {
     return (
+<<<<<<< HEAD
+      <div 
+        className="flex items-center gap-1.5 text-xs text-red-400/80"
+        role="alert"
+      >
+        <Fuel size={16} />
+=======
       <div className="flex items-center gap-1.5 text-xs text-red-400">
         <Icon icon={Fuel} dense />
+>>>>>>> upstream/main
         <span>Fee unavailable</span>
       </div>
     );
@@ -109,11 +125,22 @@ export default function NetworkFeeIndicator() {
 
   // 3. Main Data Display
   return (
+<<<<<<< HEAD
+    <div 
+      className="flex items-center gap-1.5 px-3 py-1.5 rounded-full bg-slate-800/40 border border-slate-700 hover:border-slate-600 transition-all group cursor-default"
+      title={`Current network fee: ${feeData.baseFee} stroops`}
+    >
+      <Fuel 
+        size={16} 
+        className={`transition-colors duration-300 ${getFeeColor(feeData.baseFee)}`} 
+        aria-hidden="true"
+=======
     <div className="flex items-center gap-1.5 px-3 py-1.5 rounded-full bg-slate-800/50 border border-slate-700 hover:border-slate-600 transition-colors group">
       <Icon 
         icon={Fuel}
         dense
         className={`transition-colors ${getFeeColor(feeData.baseFee)}`} 
+>>>>>>> upstream/main
       />
       <div className="flex items-baseline gap-1">
         <span 
@@ -130,6 +157,9 @@ export default function NetworkFeeIndicator() {
     </div>
   );
 }
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/components/ui/Tooltip.tsx b/src/components/ui/Tooltip.tsx
index 3bdbc49..657ed3d 100644
--- a/src/components/ui/Tooltip.tsx
+++ b/src/components/ui/Tooltip.tsx
@@ -1,37 +1,85 @@
+<<<<<<< HEAD
+/**
+ * Shared Tooltip Component.
+ * Displays a non-interactive popover containing descriptive text when 
+ * the user hovers over or focuses on the child element.
+ */
+=======
 "use client";
+>>>>>>> upstream/main
 
 import React, { useState } from "react";
 
+/**
+ * Props for the Tooltip component.
+ */
 interface TooltipProps {
+  /** The text content to display inside the tooltip bubble */
   content: string;
+  /** The element that triggers the tooltip (usually an icon or button) */
   children: React.ReactNode;
+  /** Optional position override (defaults to top) */
+  position?: "top" | "bottom" | "left" | "right";
 }
 
-export default function Tooltip({ children, content }: TooltipProps) {
+/**
+ * A lightweight, accessible tooltip component.
+ */
+export default function Tooltip({ children, content, position = "top" }: TooltipProps) {
+  // --- Component State ---
   const [isVisible, setIsVisible] = useState(false);
 
+  // --- Style Logic ---
+  
+  /** Position-specific Tailwind classes */
+  const positionClasses = {
+    top: "bottom-full left-1/2 -translate-x-1/2 mb-2.5",
+    bottom: "top-full left-1/2 -translate-x-1/2 mt-2.5",
+    left: "right-full top-1/2 -translate-y-1/2 mr-2.5",
+    right: "left-full top-1/2 -translate-y-1/2 ml-2.5"
+  };
+
+  /** Arrow orientation classes */
+  const arrowClasses = {
+    top: "top-full left-1/2 -translate-x-1/2 border-t-slate-800",
+    bottom: "bottom-full left-1/2 -translate-x-1/2 border-b-slate-800",
+    left: "left-full top-1/2 -translate-y-1/2 border-l-slate-800",
+    right: "right-full top-1/2 -translate-y-1/2 border-r-slate-800"
+  };
+
   return (
     <div
-      className="relative inline-block"
+      className="relative inline-block group"
       onMouseEnter={() => setIsVisible(true)}
       onMouseLeave={() => setIsVisible(false)}
+      onFocus={() => setIsVisible(true)}
+      onBlur={() => setIsVisible(false)}
     >
+      {/* The trigger element */}
       {children}
+      
+      {/* The Tooltip Bubble */}
       <div
-        className={`absolute bottom-full left-1/2 -translate-x-1/2 mb-2 w-max max-w-xs transition-opacity duration-200 pointer-events-none ${
-          isVisible ? "opacity-100 translate-y-0" : "opacity-0 translate-y-1"
+        className={`absolute ${positionClasses[position]} w-max max-w-[200px] transition-all duration-200 pointer-events-none z-[60] ${
+          isVisible ? "opacity-100 scale-100" : "opacity-0 scale-95"
         }`}
+        role="tooltip"
+        aria-hidden={!isVisible}
       >
-        <div className="bg-slate-800 text-white text-xs p-2 rounded shadow-lg whitespace-normal leading-relaxed text-center">
+        <div className="bg-slate-800 border border-slate-700 text-slate-100 text-[10px] font-bold uppercase tracking-widest px-3 py-2 rounded-xl shadow-2xl shadow-black/40 whitespace-normal leading-tight text-center relative">
           {content}
-          {/* Arrow */}
-          <div className="absolute top-full left-1/2 -translate-x-1/2 border-8 border-transparent border-t-slate-800" />
+          
+          {/* Decorative Arrow */}
+          <div className={`absolute border-[5px] border-transparent ${arrowClasses[position]}`} />
         </div>
       </div>
     </div>
   );
 }
 
+<<<<<<< HEAD
+=======
 // Inconsequential change for repo health
 
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/hooks/useRecentTokens.ts b/src/hooks/useRecentTokens.ts
index ed561d0..0d4e449 100644
--- a/src/hooks/useRecentTokens.ts
+++ b/src/hooks/useRecentTokens.ts
@@ -1,43 +1,92 @@
+/**
+ * Recent Tokens Hook.
+ * Manages a persistent list of recently used tokens (symbols) in the swap interface.
+ * Helps improve UX by providing quick access to common assets.
+ */
+
 import { useState, useEffect, useCallback } from 'react';
 
+/** localStorage key for recent token symbols */
 const STORAGE_KEY = 'tradeflow_recent_tokens';
+/** Maximum number of unique tokens to track */
 const MAX_RECENT_TOKENS = 3;
 
+/**
+ * Custom hook for managing the recent tokens list.
+ */
 export function useRecentTokens() {
+  // --- State Initialization ---
   const [recentTokens, setRecentTokens] = useState<string[]>([]);
 
+  /**
+   * Effect: Hydrate the state from localStorage on component mount.
+   * Only runs in the browser environment.
+   */
   useEffect(() => {
     if (typeof window === 'undefined') return;
 
     try {
-      const stored = localStorage.getItem(STORAGE_KEY);
-      if (stored) {
-        const parsed = JSON.parse(stored);
+      const storedData = localStorage.getItem(STORAGE_KEY);
+      if (storedData) {
+        const parsed = JSON.parse(storedData);
         if (Array.isArray(parsed)) {
-          setRecentTokens(parsed);
+          // Validate that the array contains only strings
+          const validTokens = parsed.filter(t => typeof t === 'string');
+          setRecentTokens(validTokens);
         }
       }
     } catch (error) {
-      console.warn('Error reading recent tokens from localStorage:', error);
+      console.warn('[useRecentTokens] Error loading history:', error);
     }
   }, []);
 
-  const addRecentToken = useCallback((token: string) => {
+  /**
+   * Adds a token to the top of the recent list.
+   * If the token already exists, it is moved to the front.
+   * 
+   * @param {string} tokenSymbol - The symbol of the token (e.g., "XLM").
+   */
+  const addRecentToken = useCallback((tokenSymbol: string) => {
+    if (!tokenSymbol) return;
+
     setRecentTokens((prev) => {
-      // Remove if exists to move to top
-      const filtered = prev.filter((t) => t !== token);
-      // Prepend new token and slice to max length
-      const newRecent = [token, ...filtered].slice(0, MAX_RECENT_TOKENS);
+      // 1. Remove duplicates to ensure uniqueness
+      const filteredList = prev.filter((t) => t !== tokenSymbol);
       
+      // 2. Prepend the new token and enforce the size limit
+      const updatedHistory = [tokenSymbol, ...filteredList].slice(0, MAX_RECENT_TOKENS);
+      
+      // 3. Persist the updated list for future sessions
       try {
-        localStorage.setItem(STORAGE_KEY, JSON.stringify(newRecent));
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(updatedHistory));
       } catch (error) {
-        console.warn('Error saving recent tokens:', error);
+        console.warn('[useRecentTokens] Failed to persist update:', error);
       }
-      return newRecent;
+      
+      return updatedHistory;
     });
   }, []);
 
+<<<<<<< HEAD
+  /**
+   * Resets the recent tokens history.
+   */
+  const clearHistory = useCallback(() => {
+    setRecentTokens([]);
+    localStorage.removeItem(STORAGE_KEY);
+  }, []);
+
+  return { 
+    /** The current array of recently used token symbols */
+    recentTokens, 
+    /** Function to track a new token usage */
+    addRecentToken,
+    /** Function to wipe the history */
+    clearHistory
+  };
+}
+=======
   return { recentTokens, addRecentToken };
 }
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/hooks/useWatchlist.ts b/src/hooks/useWatchlist.ts
index 9f0fae2..5497a73 100644
--- a/src/hooks/useWatchlist.ts
+++ b/src/hooks/useWatchlist.ts
@@ -107,4 +107,7 @@ export function useWatchlist() {
   };
 }
 
+<<<<<<< HEAD
+=======
 // Maintenance: minor update
+>>>>>>> upstream/main
diff --git a/src/lib/format.ts b/src/lib/format.ts
index 42b2d43..a08a64a 100644
--- a/src/lib/format.ts
+++ b/src/lib/format.ts
@@ -1,19 +1,41 @@
 /**
+<<<<<<< HEAD
+ * Data formatting utilities for the TradeFlow application.
+ * Provides consistent formatting for currency, dates, addresses, and percentages.
+ */
+
+/**
+ * Formats raw blockchain currency values into a human-readable USD string.
+ * Specifically handles Stellar/Soroban assets with 7 decimal places (standard for USDC).
+ * 
+ * @param {number | string} amount - The raw amount from the blockchain (e.g., 10,000,000 for 1.00 USDC).
+ * @returns {string} A localized currency string (e.g., "$1.00").
+ */
+export const formatCurrency = (amount: number | string): string => {
+  // 1. Convert string input to number if necessary
+=======
  * Format currency values
  * @param amount - Amount to format
  * @param isRaw - If true, divides by 10^7 (standard for USDC on Stellar)
  * @returns Formatted USD string
  */
 export const formatCurrency = (amount: number | string, isRaw: boolean = true): string => {
+>>>>>>> upstream/main
   const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
   
   if (isNaN(numAmount)) {
     return '$0.00';
   }
   
+<<<<<<< HEAD
+  // 2. Stellar assets like USDC typically use 7 decimal places
+  // We divide by 10^7 to get the actual unit value
+  const usdcAmount = numAmount / 10000000;
+=======
   // If raw from blockchain (USDC has 7 decimals), divide by 10^7
   // Otherwise, use the number as is (pre-calculated USD)
   const usdcAmount = isRaw ? numAmount / 10000000 : numAmount;
+>>>>>>> upstream/main
   
   // 3. Format using standard US locale settings
   return new Intl.NumberFormat('en-US', {