diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..ccdb195 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,389 @@ +# GitHub Copilot Instructions for RangisNet + +## Repository Overview + +RangisNet is a **Harmonic Execution & Asset Cognition Layer** for Avalanche blockchain that transforms network activity into real-time, multi-sensory intelligence using sound, color, resonance patterns, and harmonic signals. + +**Key Purpose**: Make blockchain interaction accessible through audio, visual, and haptic feedback, especially for Blind and Neurodivergent users. + +## Technology Stack + +### Frontend (Web/) +- **Framework**: Next.js 14.2.34 with React 18.3.1 +- **Language**: TypeScript 5.4.5 +- **Blockchain**: Thirdweb SDK, ethers.js 5.7.2 +- **3D Graphics**: Three.js, React Three Fiber +- **Build**: Next.js build system + +### Backend +- **APIs**: Hono framework (X402 integration) +- **Real-time**: WebSocket for harmonic streaming +- **Blockchain**: Avalanche C-Chain, Subnets, LayerZero bridge + +### Metrics Engine +- **Location**: `Engines/`, `McCrea-Metrics/` +- **Technology**: Python, JavaScript +- **Purpose**: McCrea Market Metrics™ proprietary algorithms + +## Security Guidelines + +### Critical Security Rules + +1. **Never commit secrets or API keys** + - Use `.env` files (add to `.gitignore`) + - Reference environment variables only + - See `.env.example` for required variables + +2. **Dependency Management** + - Run `npm audit` before commits + - Keep React at 18.x (avoid React 19 RCE vulnerability CVE-2025-55182) + - Update dependencies regularly but test thoroughly + - See `SECURITY.md` for known vulnerabilities + +3. **Input Validation** + - Sanitize all user inputs + - Validate wallet addresses before transactions + - Check transaction parameters before signing + - Use TypeScript strict mode + +4. **Smart Contract Security** + - Audit all contract changes + - Use OpenZeppelin libraries + - Test extensively on testnets first + - Implement reentrancy guards + +### Known Security Considerations + +- **@coinbase/wallet-sdk**: High severity in Thirdweb SDK (non-critical, monitoring for updates) +- **@openzeppelin/contracts**: Development dependency issues (not in production) +- **elliptic**, **ws**, **axios**: Transitive dependencies from LayerZero (isolated impact) + +See `SECURITY.md` and `SECURITY_STATUS.md` for complete details. + +## Accessibility Requirements + +### WCAG 2.1 AA Compliance + +RangisNet is designed for **2 billion+ users with accessibility needs**, including Blind and Neurodivergent individuals. + +#### Screen Reader Support + +1. **ARIA Labels Required** + - All interactive elements must have `aria-label` or `aria-labelledby` + - Use `role` attributes appropriately (`button`, `navigation`, `main`, etc.) + - Maintain live regions for dynamic content updates + +2. **Semantic HTML** + - Use proper heading hierarchy (h1 → h2 → h3) + - Use ` + ); +}; +``` + +### File Organization + +``` +Web/ +├── src/ +│ ├── components/ # Reusable UI components +│ ├── lib/ # Utility libraries +│ ├── app/ # Next.js app router pages +│ └── accessibility.ts # Accessibility helpers +├── public/ # Static assets +└── styles/ # Global styles +``` + +### Naming Conventions + +- **Components**: PascalCase (`WalletConnect.tsx`) +- **Files**: kebab-case (`market-data.ts`) +- **Functions**: camelCase (`calculateMetrics`) +- **Constants**: UPPER_SNAKE_CASE (`API_ENDPOINT`) +- **CSS Classes**: kebab-case (`wallet-button`) + +## Testing + +### Before Committing + +```bash +# In Web/ directory +npm run lint # Check code style +npm run build # Verify build succeeds +npm audit # Check for vulnerabilities +``` + +### Testing Checklist + +- [ ] Code builds without errors +- [ ] No TypeScript errors +- [ ] Linting passes +- [ ] Accessibility features work +- [ ] Tested on actual device/browser +- [ ] No console errors in browser + +## Workflow Guidelines + +### Wallet Connection Flow + +1. User clicks "Connect Wallet" +2. Thirdweb modal appears +3. User selects wallet provider +4. Wallet connection confirmed +5. **Announce via screen reader**: "Wallet connected successfully" +6. **Provide haptic feedback**: Success pattern +7. Update UI with wallet address + +### Transaction Flow + +1. User initiates transaction +2. **Announce via screen reader**: "Transaction pending" +3. Show loading state (accessible) +4. Wait for confirmation +5. **Announce via screen reader**: "Transaction confirmed" or "Transaction failed" +6. **Provide haptic feedback**: Success or error pattern +7. Update UI with result + +### Error Handling + +```typescript +// Always provide clear, actionable error messages +try { + await connectWallet(); +} catch (error) { + const message = 'Failed to connect wallet. Please check your wallet extension is installed and unlocked.'; + + // Visual + showErrorToast(message); + + // Screen reader + announceError(message); + + // Haptic + triggerHapticFeedback(0, 'error'); + + console.error('Wallet connection error:', error); +} +``` + +## Deployment + +### Environment Variables Required + +```bash +# Blockchain +NEXT_PUBLIC_THIRDWEB_CLIENT_ID= +NEXT_PUBLIC_AVALANCHE_RPC_URL= + +# APIs (optional) +YOUMIO_API_KEY= +PYTH_API_KEY= + +# Never commit these to git! +``` + +### Build Commands + +```bash +cd Web/ +npm install +npm run build +npm start # Production server +``` + +## Resources + +### Documentation +- [SECURITY.md](../SECURITY.md) - Security policy and vulnerabilities +- [README.md](../README.md) - Project overview +- [WHITEPAPER.md](../WHITEPAPER.md) - Technical details +- [WALLET_EXPERIENCE.md](../WALLET_EXPERIENCE.md) - User flows + +### External Standards +- [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) - Accessibility guidelines +- [ARIA Practices](https://www.w3.org/WAI/ARIA/apg/) - ARIA patterns +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) - Security + +### Tools +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) +- [WAVE Browser Extension](https://wave.webaim.org/extension/) +- [axe DevTools](https://www.deque.com/axe/devtools/) + +## Getting Help + +### For Security Issues +**Do not create public issues!** +- GitHub Security Advisories (preferred) +- Email: security@rangis.net + +### For General Questions +- Check documentation first +- Review existing issues +- Create new issue with clear description + +## McCrea Market Metrics™ Specifics + +### Metric Ranges +- `stability_index`: 0-1 (0 = unstable, 1 = stable) +- `execution_risk`: 0-1 (0 = low risk, 1 = high risk) +- `comfort_band`: boolean (true = safe to trade) +- `liquidity_score`: 0-100 (higher = more liquid) + +### Integration Points +```typescript +import { calculateMetrics } from '@/lib/mccrea-metrics-m3'; + +const metrics = await calculateMetrics(symbol); + +// Announce to user +announceConfidence( + metrics.stability_index, + metrics.comfort_band ? 'trade' : 'hold', + { ariaLive: true, voiceEnabled: true, hapticsEnabled: true } +); +``` + +## Common Tasks + +### Adding a New Component + +1. Create file in `Web/src/components/` +2. Use TypeScript with proper interfaces +3. Include ARIA labels and roles +4. Test keyboard navigation +5. Test with screen reader +6. Export from component + +### Fixing a Security Vulnerability + +1. Check `SECURITY.md` for known issues +2. Run `npm audit` to identify +3. Update package if fix available +4. Test thoroughly after update +5. Update `SECURITY.md` if needed +6. Document in PR description + +### Improving Accessibility + +1. Identify the issue (use axe DevTools) +2. Check WCAG 2.1 guidelines +3. Implement fix with proper ARIA +4. Test with screen reader +5. Test keyboard navigation +6. Document in `accessibility.ts` if reusable + +--- + +**Remember**: RangisNet's mission is to make blockchain accessible to everyone, especially those with disabilities. Every change should consider the 2B+ users who depend on our accessibility features. diff --git a/ACCESSIBILITY_TESTING_GUIDE.md b/ACCESSIBILITY_TESTING_GUIDE.md new file mode 100644 index 0000000..178d804 --- /dev/null +++ b/ACCESSIBILITY_TESTING_GUIDE.md @@ -0,0 +1,422 @@ +# Accessibility Testing Guide for RangisNet + +## Overview + +RangisNet is designed to be accessible to 2 billion+ users with accessibility needs, including Blind and Neurodivergent individuals. This guide outlines testing procedures to ensure WCAG 2.1 AA compliance. + +## Testing Checklist + +### 1. Screen Reader Testing + +#### Windows - NVDA (Free) +```bash +# Download from: https://www.nvaccess.org/download/ +# Install and run NVDA +# Navigate to: http://localhost:3000 +``` + +**Test Cases:** +- [ ] Navigate to the homepage + - Verify: "Welcome to RangisNet" is announced + - Verify: Skip to main content link works +- [ ] Connect Wallet + - Verify: "Connect Wallet" button is announced + - Verify: Modal opens with announcement + - Verify: Wallet connection success is announced + - Verify: Address is read clearly +- [ ] Execute Transaction + - Verify: Transaction pending announcement + - Verify: Progress updates announced + - Verify: Success/failure announced clearly +- [ ] Navigate with Tab Key + - Verify: All interactive elements reachable + - Verify: Logical tab order + - Verify: Focus indicators visible + +#### macOS - VoiceOver (Built-in) +```bash +# Enable: System Preferences > Accessibility > VoiceOver +# Or press: Cmd + F5 +# Navigate to: http://localhost:3000 +``` + +**Test Cases:** +- [ ] Use VoiceOver rotor to list headings + - Verify: Proper heading hierarchy +- [ ] Use VoiceOver to navigate forms + - Verify: Labels associated with inputs + - Verify: Error messages announced +- [ ] Test with Safari and Chrome + - Verify: Consistent behavior across browsers + +#### Windows - JAWS (Commercial) +```bash +# Download trial: https://www.freedomscientific.com/downloads/ +# Navigate to: http://localhost:3000 +``` + +**Test Cases:** +- [ ] Test all interactive elements +- [ ] Verify ARIA live regions work +- [ ] Test with Edge and Chrome + +### 2. Keyboard Navigation Testing + +**No mouse required!** + +#### Basic Navigation +- [ ] Tab through all interactive elements + - Expected: Clear focus indicators (blue outline) + - Expected: Logical order (top to bottom, left to right) +- [ ] Shift+Tab to navigate backwards + - Expected: Reverse order works correctly +- [ ] Enter/Space to activate buttons + - Expected: Buttons respond to keyboard +- [ ] Escape to close modals + - Expected: Focus returns to trigger element + +#### Advanced Navigation +- [ ] Use arrow keys in dropdowns + - Expected: Options selectable with arrows +- [ ] Type to search in select elements + - Expected: Quick selection works +- [ ] Navigate forms with Tab + - Expected: Skip to next form field + +#### Keyboard Shortcuts +Document any custom shortcuts: +- [ ] None currently implemented +- [ ] Future: Consider adding global shortcuts (e.g., "C" to connect wallet) + +### 3. Visual Accessibility Testing + +#### Color Contrast +Use WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/ + +**Current Colors:** +- [ ] Body text (#ffffff on #1a1a2e) + - Result: Ratio 13.84:1 ✓ (Exceeds WCAG AAA) +- [ ] Button text (#ffffff on #667eea) + - Result: Ratio 4.58:1 ✓ (Meets WCAG AA) +- [ ] Success (#00ff88 on dark) + - Result: Needs verification +- [ ] Error (#ff0088 on dark) + - Result: Needs verification +- [ ] Warning (#ffa500 on dark) + - Result: Needs verification + +**Test Tool:** +```bash +# Chrome Extension: WCAG Color Contrast Checker +# Or use: https://webaim.org/resources/contrastchecker/ +``` + +#### Text Sizing +- [ ] Zoom to 200% in browser + - Expected: Content still readable and usable + - Expected: No horizontal scrolling required + - Expected: No text truncation +- [ ] Change browser base font size + - Expected: Layout adapts properly + +#### Visual Focus Indicators +- [ ] Tab through interactive elements + - Expected: Blue outline (3px) visible on all elements + - Expected: Outline doesn't blend with background + - Expected: Sufficient contrast (3:1 minimum) + +### 4. Motion and Animation Testing + +#### Reduced Motion +```bash +# Windows: Settings > Ease of Access > Display > Show animations +# macOS: System Preferences > Accessibility > Display > Reduce motion +# Linux: GNOME Settings > Accessibility > Reduce motion +``` + +**Test Cases:** +- [ ] Enable reduced motion preference +- [ ] Reload RangisNet +- [ ] Verify: Animations are minimal or removed +- [ ] Verify: Transitions still function but without motion +- [ ] Test transaction feedback + - Expected: No sliding animations + - Expected: Haptic feedback still works + +#### Auto-playing Content +- [ ] Check for auto-playing audio + - Expected: None present (user must enable) +- [ ] Check for auto-playing video + - Expected: None present or has pause control + +### 5. Haptic Feedback Testing + +**Requires mobile device or device with vibration** + +#### Test on Mobile +- [ ] Connect wallet + - Expected: Success vibration (double pulse) +- [ ] Execute transaction + - Pending: Continuous gentle pulse + - Success: Strong double pulse + - Error: Long warning pulse +- [ ] Receive error + - Expected: Error vibration pattern + +#### Disable Option +- [ ] Verify users can disable haptics + - Location: TBD - Needs settings page + - Expected: No vibration when disabled + +### 6. Voice Feedback Testing + +#### Web Speech API +**Requires browser with Speech Synthesis support** + +- [ ] Enable voice feedback (if implemented) +- [ ] Connect wallet + - Expected: "Wallet connected successfully" spoken +- [ ] Transaction status + - Pending: "Transaction pending" + - Success: "Transaction confirmed" + - Error: "Transaction failed" +- [ ] Confidence announcements + - High: "Feels confident at 85%. Ready to trade?" + - Medium: "Moderate confidence at 60%" + - Low: "Low confidence at 30%. Recommend holding" + +#### Voice Settings +- [ ] Test with different voices (if available) +- [ ] Test volume control +- [ ] Test speech rate control +- [ ] Verify users can disable voice + +### 7. Mobile Accessibility Testing + +#### iOS with VoiceOver +```bash +# Settings > Accessibility > VoiceOver > On +# Triple-click Home/Power button to toggle +``` + +**Test Cases:** +- [ ] Swipe right/left to navigate +- [ ] Double-tap to activate +- [ ] Three-finger swipe to scroll +- [ ] Rotor for quick navigation +- [ ] Test in Safari and Chrome + +#### Android with TalkBack +```bash +# Settings > Accessibility > TalkBack > On +# Volume keys to toggle +``` + +**Test Cases:** +- [ ] Swipe right/left to navigate +- [ ] Double-tap to activate +- [ ] Two-finger swipe to scroll +- [ ] Test in Chrome and Firefox + +#### Touch Target Size +- [ ] Measure interactive elements + - Expected: Minimum 44x44 pixels + - Use: Browser DevTools or ruler + +### 8. Automated Testing Tools + +#### axe DevTools (Browser Extension) +```bash +# Install: https://www.deque.com/axe/devtools/ +# Open DevTools > axe DevTools tab +# Click "Scan ALL of my page" +``` + +**Expected Results:** +- [ ] 0 Critical issues +- [ ] 0 Serious issues +- [ ] Document moderate issues +- [ ] Document minor issues + +#### WAVE (Browser Extension) +```bash +# Install: https://wave.webaim.org/extension/ +# Navigate to page +# Click WAVE icon +``` + +**Check for:** +- [ ] Errors: Must fix all +- [ ] Alerts: Investigate each +- [ ] Features: Verify present (ARIA, labels) +- [ ] Structure: Verify proper (headings, landmarks) +- [ ] Contrast: Must meet WCAG AA + +#### Lighthouse (Chrome DevTools) +```bash +# Chrome DevTools > Lighthouse tab +# Select "Accessibility" category +# Click "Generate report" +``` + +**Target Score:** +- [ ] Accessibility: 90+ (Aim for 100) +- [ ] Best Practices: 90+ +- [ ] SEO: 90+ +- [ ] Performance: 80+ + +### 9. Common Issues to Check + +#### Images +- [ ] All images have alt text + - Decorative: alt="" (empty) + - Informative: Descriptive alt text +- [ ] SVG icons have accessible names + - Use: aria-label or title element + +#### Forms +- [ ] All inputs have associated labels + - Use: `