Add comprehensive GitHub Copilot instructions with validated build and test commands

Co-authored-by: 0xrinegade <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,163 @@
+# SVMSeek Wallet Development Instructions
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Build
+- Install dependencies: `yarn install --frozen-lockfile` -- takes 2.5 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
+- Build production: `yarn build` -- takes 1.5 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
+- Build extensions: `./scripts/build-extensions.sh` -- takes 2 seconds.
+- Format code: `yarn fix:prettier` -- takes 1 second.
+
+### Development Workflow
+- Start development server: `yarn start` -- may take 2-3 minutes to fully compile. NEVER CANCEL. Set timeout to 10+ minutes.
+- Test production build: `yarn global add serve && serve -s build -p 3001`
+- Run unit tests: `yarn test --watchAll=false --coverage=false` -- takes 1.2 minutes. NEVER CANCEL. Set timeout to 5+ minutes.
+
+### Browser Extensions
+- Build all extensions: `./scripts/build-extensions.sh`
+- Produces ZIP files for Chrome (v3), Firefox (v2), Safari (v2), Edge (v3)
+- Extensions are ~3.3MB each and ready for store submission
+- Extension builds require successful `yarn build` first
+
+### E2E Testing
+- Install browsers: `yarn playwright:install` -- takes 15 seconds. May show dependency warnings (normal in CI).
+- Run E2E tests: `yarn test:e2e` -- may fail with localStorage issues in headless mode (known limitation)
+- Use `yarn test:e2e-headed` for better compatibility
+
+## Validation
+
+- ALWAYS run through at least one complete end-to-end scenario after making changes.
+- ALWAYS validate the production build works: `yarn build && serve -s build`
+- Test the wallet interface at `/wallet` route to ensure core functionality works
+- Browser extension builds should always succeed if main build succeeds
+- Always run `yarn fix:prettier` before committing to maintain code style
+
+## Platform Support
+
+### Web Application
+- Node.js v20.18.0+ required (check with `node --version`)
+- Yarn v1.22.0+ recommended
+- Builds successfully in 1.5 minutes
+- Serves on localhost:3000 (dev) or any port with `serve -s build`
+
+### Browser Extensions
+- Chrome: Manifest V3, 3.3MB
+- Firefox: Manifest V2, 3.3MB  
+- Safari: Manifest V2, 3.3MB
+- Edge: Manifest V3, 3.3MB
+- Build time: 2 seconds
+
+### Mobile (Android)
+- Requires Java 17+ (current system has Java 17)
+- Android build FAILS due to Java 21 requirement conflict
+- DO NOT attempt Android builds - requires configuration fixes
+- Script: `./scripts/build-mobile.sh` (will fail)
+
+## Common Tasks
+
+### Repository Structure
+```
+svmseek/
+├── src/                    # React TypeScript source
+│   ├── components/         # React components
+│   │   ├── Explorer/       # Blockchain explorer components
+│   │   ├── ChatInterface.tsx
+│   │   └── GlassContainer.tsx
+│   ├── pages/              # Page components
+│   ├── utils/              # Utility functions
+│   └── context/            # React context providers
+├── public/                 # Static assets
+├── docs/                   # Documentation
+├── extension/              # Browser extension files
+├── scripts/                # Build and utility scripts
+├── e2e/                    # E2E test files
+└── build/                  # Production build output
+```
+
+### Key Technologies
+- React 19 with TypeScript
+- Material-UI v7 for components
+- Solana Web3.js for blockchain
+- Styled Components for CSS-in-JS
+- Playwright for E2E testing
+- Capacitor for mobile (broken)
+
+### File Listings
+
+#### Root Directory
+```
+.github/           # GitHub Actions workflows
+docs/              # Comprehensive documentation
+extension/         # Browser extension source
+scripts/           # Build automation scripts
+src/               # Application source code
+package.json       # Dependencies and scripts
+yarn.lock          # Dependency lock file
+.nvmrc             # Node version requirement (v20.18.0)
+```
+
+#### Package.json Scripts (Key Ones)
+```json
+{
+  "start": "craco start",
+  "build": "craco build", 
+  "test": "craco test",
+  "test:e2e": "npx playwright test --config=playwright.simple.config.ts",
+  "fix:prettier": "prettier \"src/**/*.js\" \"extension/src/*.js\" --write",
+  "build:extension-enhanced": "./scripts/build-extensions.sh"
+}
+```
+
+## Known Issues
+
+### E2E Tests
+- May fail with localStorage access errors in headless mode
+- Use `--headed` flag for better compatibility
+- Advanced performance tests fail due to security restrictions
+
+### Mobile Builds
+- Android build fails due to Java version mismatch (requires Java 21, system has Java 17)
+- DO NOT attempt mobile builds until configuration is fixed
+
+### Development Server
+- May take 2-3 minutes to fully start and serve content
+- Wait for "Compiled successfully" message before testing
+- Default port is 3000, may conflict with other services
+
+## Build Outputs
+
+### Successful Build Indicators
+- Web build: ~3MB total bundle size, multiple chunk files
+- Extension build: 4 ZIP files created (~3.3MB each)
+- Unit tests: 93 passed, 17 skipped (normal)
+
+### File Sizes (Typical)
+- Main application bundle: ~3MB total
+- Extension packages: ~3.3MB each
+- Individual chunks: 1KB to 1.2MB range
+
+## Debugging
+
+### TypeScript Warnings
+- Version warning for @typescript-eslint is normal (uses TS 5.9.2 vs supported 5.2.0)
+- Does not affect functionality
+
+### Bundle Size
+- Large bundle size warnings are normal for crypto applications
+- Consider code splitting if adding significant features
+
+### Browser Compatibility
+- Chrome: Full support
+- Firefox: Full support  
+- Safari: Full support
+- Edge: Full support
+- Mobile browsers: Supported via PWA
+
+## Documentation References
+
+- Main README: `README.md`
+- Developer Guide: `docs/developer-guide.md`
+- Build System: `docs/BUILD_SYSTEM.md`
+- Mobile Building: `docs/MOBILE_BUILD.md`

extension/extension-build-info.txt

@@ -1,13 +1,13 @@
 SVMSeek Wallet Browser Extensions
 =================================
-Build Date: Thu Jul 24 13:14:00 UTC 2025
+Build Date: Mon Aug 11 15:44:03 UTC 2025
 Extensions Built: Chrome, Firefox, Safari, Edge
 
 Extension Details:
-- chrome: 6.9M (Manifest v3)
-- firefox: 6.9M (Manifest v2)
-- safari: 6.9M (Manifest v2)
-- edge: 6.9M (Manifest v3)
+- chrome: 3.3M (Manifest v3)
+- firefox: 3.3M (Manifest v2)
+- safari: 3.3M (Manifest v2)
+- edge: 3.3M (Manifest v3)
 
 Distribution:
 - Chrome: Chrome Web Store (Manifest v3)

extension/src/background.js

@@ -54,7 +54,7 @@ function handleDisconnect(message, sender, sendResponse) {
 
 chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
   console.log('extensionChanel');
-  console.log('message.data', message.data)
+  console.log('message.data', message.data);
   if (message.channel === 'ccai_contentscript_background_channel') {
     if (message.data.method === 'connect') {
       handleConnect(message, sender, sendResponse);

extension/src/contentscript.js

@@ -21,4 +21,4 @@ window.addEventListener('ccai_injected_script_message', (event) => {
       );
     },
   );
-});
+});

extension/src/script.js

@@ -1,4 +1,3 @@
-
 window.ccai = {
   postMessage: (message) => {
     const listener = (event) => {

src/components/AddHarwareWalletDialog.js

@@ -21,9 +21,7 @@ export default function AddHardwareWalletDialog({ open, onAdd, onClose }) {
           await provider.init();
           setPubKey(provider.publicKey);
         } catch (err) {
-          devLog(
-            `received error when attempting to connect ledger: ${err}`,
-          );
+          devLog(`received error when attempting to connect ledger: ${err}`);
           if (err.statusCode === 0x6804) {
             enqueueSnackbar('Unlock ledger device', { variant: 'error' });
           }

src/components/AddTokenDialog.js

@@ -11,7 +11,7 @@ import {
   useWalletTokenAccounts,
 } from '../utils/wallet';
 import { LAMPORTS_PER_SOL, PublicKey } from '@solana/web3.js';
-import { TOKENS } from '../utils/tokens/tokens'
+import { TOKENS } from '../utils/tokens/tokens';
 import { useUpdateTokenName } from '../utils/tokens/names';
 import { useAsyncData } from '../utils/fetch-loop';
 import LoadingIndicator from './LoadingIndicator';
@@ -125,7 +125,8 @@ export default function AddTokenDialog({ open, onClose }) {
             indicatorColor="primary"
             sx={{
               marginBottom: 1,
-              borderBottom: (theme) => `1px solid ${theme.palette.background.paper}`,
+              borderBottom: (theme) =>
+                `1px solid ${theme.palette.background.paper}`,
             }}
             onChange={(e, value) => setTab(value)}
           >

src/components/BalancesList.js

@@ -3,7 +3,7 @@ import List from '@mui/material/List';
 import ListItem from '@mui/material/ListItem';
 import ListItemText from '@mui/material/ListItemText';
 import Paper from '@mui/material/Paper';
-import { logError  } from '../utils/logger';
+import { logError } from '../utils/logger';
 import {
   refreshWalletPublicKeys,
   useBalanceInfo,
@@ -101,9 +101,8 @@ export default function BalancesList() {
   const wallet = useWallet();
   const [publicKeys, loaded] = useWalletPublicKeys();
   const [showAddTokenDialog, setShowAddTokenDialog] = useState(false);
-  const [showEditAccountNameDialog, setShowEditAccountNameDialog] = useState(
-    false,
-  );
+  const [showEditAccountNameDialog, setShowEditAccountNameDialog] =
+    useState(false);
   const [showMergeAccounts, setShowMergeAccounts] = useState(false);
   const [sortAccounts, setSortAccounts] = useState(SortAccounts.None);
   const { accounts, setAccountName } = useWalletSelector();
@@ -297,7 +296,7 @@ const ButtonContainer = styled('div')(({ theme }) => ({
 export function BalanceListItem({ publicKey, expandable, setUsdValue }) {
   const wallet = useWallet();
   const balanceInfo = useBalanceInfo(publicKey);
-  const theme = useTheme()
+  const theme = useTheme();
   const connection = useConnection();
   const [open, setOpen] = useState(false);
   const [, setForceUpdate] = useState(false);
@@ -407,16 +406,16 @@ export function BalanceListItem({ publicKey, expandable, setUsdValue }) {
     price === undefined // Not yet loaded.
       ? undefined
       : price === null // Loaded and empty.
-      ? null
-      : ((amount / Math.pow(10, decimals)) * price).toFixed(2); // Loaded.
+        ? null
+        : ((amount / Math.pow(10, decimals)) * price).toFixed(2); // Loaded.
 
   if (setUsdValue && usdValue !== undefined) {
     setUsdValue(publicKey, usdValue === null ? null : parseFloat(usdValue));
   }
 
   return (
     <>
-      <ListItem  button onClick={() => expandable && setOpen((open) => !open)}>
+      <ListItem button onClick={() => expandable && setOpen((open) => !open)}>
         <ListItemIcon>
           <TokenIcon mint={mint} tokenName={tokenName} size={28} />
         </ListItemIcon>
@@ -429,9 +428,7 @@ export function BalanceListItem({ publicKey, expandable, setUsdValue }) {
                 {tokenSymbol ? ` (${tokenSymbol})` : null}
               </Title>
             }
-            secondary={
-              <AddressText>{subtitle}</AddressText>
-            }
+            secondary={<AddressText>{subtitle}</AddressText>}
           />
           <div
             style={{
@@ -466,10 +463,8 @@ function BalanceListItemDetails({ publicKey, serumMarkets, balanceInfo }) {
   const [, setDepositDialogOpen] = useState(false);
   const [tokenInfoDialogOpen, setTokenInfoDialogOpen] = useState(false);
   const [exportAccDialogOpen, setExportAccDialogOpen] = useState(false);
-  const [
-    closeTokenAccountDialogOpen,
-    setCloseTokenAccountDialogOpen,
-  ] = useState(false);
+  const [closeTokenAccountDialogOpen, setCloseTokenAccountDialogOpen] =
+    useState(false);
   const wallet = useWallet();
   const isProdNetwork = useIsProdNetwork();
   const [swapInfo] = useAsyncData(async () => {
@@ -558,7 +553,10 @@ function BalanceListItemDetails({ publicKey, serumMarkets, balanceInfo }) {
           ) : null}
         </ButtonContainer>
         <Typography variant="body2" component="div">
-          Deposit Address: <AddressText style={{ display: 'inline' }}>{publicKey.toBase58()}</AddressText>
+          Deposit Address:{' '}
+          <AddressText style={{ display: 'inline' }}>
+            {publicKey.toBase58()}
+          </AddressText>
         </Typography>
         <Typography variant="body2">
           Token Name: {tokenName ?? 'Unknown'}
@@ -568,7 +566,10 @@ function BalanceListItemDetails({ publicKey, serumMarkets, balanceInfo }) {
         </Typography>
         {mint ? (
           <Typography variant="body2" component="div">
-            Token Address: <AddressText style={{ display: 'inline' }}>{mint.toBase58()}</AddressText>
+            Token Address:{' '}
+            <AddressText style={{ display: 'inline' }}>
+              {mint.toBase58()}
+            </AddressText>
           </Typography>
         ) : null}
         <div style={{ display: 'flex', justifyContent: 'space-between' }}>

src/components/MergeAccountsDialog.js

@@ -184,7 +184,11 @@ export default function MergeAccountsDialog({ open, onClose }) {
           </div>
         </Card>
       ) : (
-        <RowContainer justify={'space-between'} height={'100%'} direction={'column'}>
+        <RowContainer
+          justify={'space-between'}
+          height={'100%'}
+          direction={'column'}
+        >
           <Title
             maxFont={'2.1rem'}
             fontSize="2.4rem"

src/components/Navbar/NavigationFrame.js

@@ -72,10 +72,8 @@ export function WalletSelector() {
   const { accounts, setWalletSelector, addAccount } = useWalletSelector();
   const [anchorEl, setAnchorEl] = useState(null);
   const [addAccountOpen, setAddAccountOpen] = useState(false);
-  const [
-    addHardwareWalletDialogOpen,
-    setAddHardwareWalletDialogOpen,
-  ] = useState(false);
+  const [addHardwareWalletDialogOpen, setAddHardwareWalletDialogOpen] =
+    useState(false);
   const [deleteMnemonicOpen, setDeleteMnemonicOpen] = useState(false);
   const [exportMnemonicOpen, setExportMnemonicOpen] = useState(false);
 
@@ -245,7 +243,7 @@ function Footer() {
   const location = useLocation();
   devLog('location', location);
 
-  if (isConnectPopup) return null
+  if (isConnectPopup) return null;
 
   return (
     <>
@@ -261,8 +259,8 @@ function Footer() {
           {location.pathname.includes('restore')
             ? 'Restore your wallet using seed phrase to get access for SPL assets management and interaction with dApps on the Solana blockchain.'
             : location.pathname.includes('create')
-            ? ' Create a cryptocurrency wallet for SPL assets management and secure connection and interaction with dApps on the Solana blockchain.'
-            : 'Web-based cryptocurrency wallet or browser extension for SPL assets management and securely connect and interact with dApps on the Solana blockchain.'}
+              ? ' Create a cryptocurrency wallet for SPL assets management and secure connection and interaction with dApps on the Solana blockchain.'
+              : 'Web-based cryptocurrency wallet or browser extension for SPL assets management and securely connect and interact with dApps on the Solana blockchain.'}
         </span>{' '}
         <Button
           variant="outlined"