EazyNavigator

Lightweight WebSDK enabling AI agents to observe and interact with web pages.

Features

• 🔍 DOM Observation - Extract structured page data automatically
• 🤖 AI Actions - Execute click, fill, navigate, and 6+ other actions
• 🔌 WebSocket Communication - Real-time bidirectional messaging with MCP server
• 🎨 Visual Highlighting - Provide user feedback for AI actions
• 🔒 Secure - Built-in XSS protection, input sanitization, and domain whitelisting
• 📦 Lightweight - Only 14.9 KB gzipped (ES module)
• 🌐 Cross-browser - Works on Chrome, Firefox, Safari, and Edge
• ⚡ Fast - Observation in <100ms, actions in <50ms
• 🧪 Well-tested - 100+ tests with comprehensive coverage

Quick Start

Installation

Via NPM

npm install @easypilot/eazy-navigator

Via Yarn

yarn add @easypilot/eazy-navigator

Via CDN

<script type="module">
  import { EazyNavigator } from 'https://cdn.jsdelivr.net/npm/@easypilot/eazy-navigator/dist/eazy-navigator.es.js';
</script>

Basic Usage

<script type="module">
  import { EazyNavigator } from '@easypilot/eazy-navigator';

  // Initialize the SDK
  const navigator = new EazyNavigator({
    mcpServerUrl: 'wss://your-mcp-server.com',
    apiKey: 'your-api-key'
  });

  // Initialize and connect
  await navigator.init();
  await navigator.connect();

  // SDK is now observing the page and ready for AI commands!
</script>

Configuration

Constructor Options

interface NavigatorConfig {
  // Required
  mcpServerUrl: string;        // WebSocket server URL
  apiKey: string;              // API key for authentication

  // Optional
  sessionId?: string;          // Session identifier (auto-generated if not provided)
  autoObserve?: boolean;       // Auto-observe page changes (default: true)
  observeInterval?: number;    // Observation interval in ms (default: 1000)
  allowedDomains?: string[];   // Whitelist of allowed domains (empty = all allowed)
  debug?: boolean;             // Enable debug logging (default: false)
  highlightColor?: string;     // Color for element highlighting (default: '#FFD700')
  reconnect?: boolean;         // Auto-reconnect on disconnect (default: true)
  reconnectInterval?: number;  // Reconnect interval in ms (default: 3000)
}

Example with All Options

const navigator = new EazyNavigator({
  mcpServerUrl: 'wss://mcp.easypilot.com',
  apiKey: 'your-api-key',
  sessionId: 'custom-session-id',
  autoObserve: true,
  observeInterval: 2000,
  allowedDomains: ['example.com', '*.example.com'],
  debug: true,
  highlightColor: '#00FF00',
  reconnect: true,
  reconnectInterval: 5000
});

Core Methods

Initialization

// Initialize the SDK
await navigator.init();

// Connect to MCP server
await navigator.connect();

// Disconnect from server
await navigator.disconnect();

// Check status
console.log(navigator.isInitialized());  // true/false
console.log(navigator.isConnected());    // true/false

DOM Observation

// Manual observation (returns immediately)
const observation = navigator.observe();

console.log(observation.elements);  // Array of interactive elements
console.log(observation.forms);     // Array of forms
console.log(observation.viewport);  // Viewport info

Action Execution

// Execute a single action
const result = await navigator.executeAction({
  type: 'click',
  selector: '#submit-button'
});

// Execute multiple actions in sequence
const results = await navigator.executeActions([
  { type: 'fill', selector: '#email', value: '[email protected]' },
  { type: 'fill', selector: '#password', value: 'secret' },
  { type: 'click', selector: '#login-button' }
]);

Supported Actions

| Action Type | Description | Parameters | |------------|-------------|------------| | click | Click an element | selector | | fill | Fill input field | selector, value | | navigate | Navigate to URL | url, waitForLoad? | | submit | Submit a form | selector, waitForNavigation? | | scroll | Scroll to element or coordinates | selector?, x?, y? | | select | Select dropdown option | selector, value | | hover | Hover over element | selector | | focus | Focus an element | selector | | blur | Blur an element | selector |

Visual Highlighting

// Highlight an element
const highlightId = navigator.highlight('#button', {
  color: '#FF0000',
  duration: 2000,      // Auto-remove after 2s
  style: 'pulse',      // 'solid', 'dashed', 'pulse', 'glow'
  label: 'Click here'
});

// Remove highlight
navigator.removeHighlight(highlightId);

// Clear all highlights
navigator.clearHighlights();

// Get active highlights
const highlights = navigator.getActiveHighlights();

Security Features

// Get security violations
const violations = navigator.getSecurityViolations();

// Clear violation history
navigator.clearSecurityViolations();

// Update security config
navigator.updateSecurityConfig({
  sanitizeInputs: true,
  blockDangerousSelectors: true,
  maxInputLength: 5000
});

// Get current security config
const config = navigator.getSecurityConfig();

Events

Listen to SDK events:

// Initialization
navigator.on('initialized', (data) => {
  console.log('SDK initialized', data.sessionId);
});

// Connection
navigator.on('connected', () => {
  console.log('Connected to MCP server');
});

navigator.on('disconnected', () => {
  console.log('Disconnected from MCP server');
});

// Observations
navigator.on('observation:start', () => {
  console.log('Starting observation...');
});

navigator.on('observation:complete', (observation) => {
  console.log('Observation complete', observation);
});

// Actions
navigator.on('action:start', (action) => {
  console.log('Action starting', action);
});

navigator.on('action:success', (result) => {
  console.log('Action succeeded', result);
});

navigator.on('action:failed', (result) => {
  console.log('Action failed', result);
});

// Security
navigator.on('security:violation', (violation) => {
  console.log('Security violation detected', violation);
});

// Errors
navigator.on('error', (error) => {
  console.error('SDK error', error);
});

Examples

Check out the examples directory for complete working demos:

• Basic Usage - Simple initialization and connection
• With Forms - Form filling and submission
• Advanced Actions - All action types
• Visual Highlighting - Element highlighting
• Security Features - Security and validation
• Full Integration - Complete WebSocket flow

Browser Support

| Browser | Version | Status | |---------|---------|--------| | Chrome | 90+ | ✅ Fully supported | | Firefox | 88+ | ✅ Fully supported | | Safari | 14+ | ✅ Fully supported | | Edge | 90+ | ✅ Fully supported |

Performance

Measured on modern hardware with typical websites:

| Metric | Target | Actual | |--------|--------|--------| | Bundle Size (gzipped) | <50 KB | 14.9 KB ✅ | | SDK Initialization | <100ms | ~40ms ✅ | | Page Observation | <100ms | ~60ms ✅ | | Click Action | <50ms | ~20ms ✅ | | Fill Action | <50ms | ~25ms ✅ |

API Documentation

For detailed API documentation, see docs/API.md.

Integration Guide

For step-by-step integration instructions, see docs/INTEGRATION.md.

Troubleshooting

Having issues? Check out the troubleshooting guide.

Development

Building

npm run build

Testing

npm test

Running Examples

npm run dev
# Open http://localhost:5173/examples/

Mock MCP Server

For testing without a real MCP server:

node tests/mock-mcp-server.ts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Links

• Documentation
• Examples
• Changelog
• Issues

Support

For questions and support, please open an issue on GitHub.

Built with ❤️ by the EazyPilot Team