---
slug: "vibe-vibe-eyes-client"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/monteslu/vibe-eyes-client@main/README.md"
repo: "https://github.com/monteslu/vibe-eyes-client"
source_file: "README.md"
branch: "main"
---
# Vibe Eyes Client

A lightweight client library to integrate browser games with the [Vibe Eyes MCP debug server](https://github.com/monteslu/vibe-eyes) for real-time debugging, visualization, and analysis.

This allows AI to SEE the game it's working on in real time!

<img src="happy.jpg" alt="Happy Face" width="50%">

## Features

- Automatic canvas screenshot capture and streaming
- Console log and error collection with timestamps
- Global error and unhandled promise rejection handling
- SVG visualization display in a dedicated debug window
- Complete debug stats with SVG size measurements
- Minimal performance impact on games
- Robust error handling with graceful connection recovery
- Multiple build formats (UMD, ESM, IIFE)

## What's New in 1.1.0

- **Disconnected SVG Display**: Debug window now works even when not connected to server
- **Connection Status Visualization**: Show real-time connection status with visual feedback
- **Smart Window Positioning**: Position debug window relative to game window (right, left, top, bottom)
- **Responsive Defaults**: Debug window size defaults to 75% of game window dimensions
- **Improved Error Handling**: Better handling of window closures and reconnection scenarios

## Installation

```bash
npm install vibe-eyes-client
```

Or include directly in your HTML:

```html
<script src="https://unpkg.com/vibe-eyes-client/dist/vibe-eyes.min.js"></script>
```

## Usage

### Basic Integration

```js
// Initialize with default settings (auto-connects to http://localhost:8869)
// Available globally when using the script tag
// The client will automatically start capturing once connected
initializeVibeEyes();

// Or use the existing client instance directly
window.VibeEyesClient.initialize();
```

### Custom Configuration

```js
// Initialize with custom settings (when included via script tag)
initializeVibeEyes({
  serverUrl: 'http://your-debug-server:8869',
  captureDelay: 2000,   // Screenshot every 2 seconds
  maxLogs: 50,          // Store more logs
  canvasId: 'my-canvas' // Specific canvas to capture
});

// Or when using as a module
import { initializeVibeEyes } from 'vibe-eyes-client';

initializeVibeEyes({
  serverUrl: 'http://your-debug-server:8869',
  captureDelay: 2000,
  canvasId: 'game-canvas'
});
```

### Manual Control

```js
// Get the client instance
const client = window.VibeEyesClient;

// Explicitly stop/restart capturing if needed
client.stopCaptureLoop();
client.startCaptureLoop();
```

### Displaying SVG Visualizations

Vibe Eyes MCP server sends back SVG visualizations that you can display in a dedicated debug window:

```js
// Get the client from initialization
const client = initializeVibeEyes();

// Enable SVG display - opens a new debug window with SVG and stats
client.enableSvgDisplay();

// You can optionally provide a custom container
client.enableSvgDisplay({
  container: '#my-custom-container' // Optional existing container element
});

// Configure the debug window position and size (all options are optional)
const client = initializeVibeEyes({
  serverUrl: 'http://localhost:8869',
  debugWindow: {
    // All debugWindow properties are optional with sensible defaults
    width: 500,                // Optional: Width in pixels (default: 75% of game window width)
    height: 600,               // Optional: Height in pixels (default: 75% of game window height)
    position: 'right'          // Optional: Position relative to game window (default: 'right')
    // Possible positions: 'right', 'left', 'top', 'bottom', 'detached'
  }
});

// Toggle the display on/off
client.toggleSvgDisplay();

// Disable the display (closes the debug window)
client.disableSvgDisplay();
```

The debug window shows:
- The SVG visualization at the top
- Complete response statistics at the bottom, including SVG size
- Updates in real-time as new data arrives from the server

## Configuration Options

All configuration options are optional and have sensible defaults.

### Client Initialization Options

| Option | Default | Description |
|--------|---------|-------------|
| serverUrl | 'http://localhost:8869' | URL of the Vibe Eyes MCP server |
| captureDelay | 1000 | Milliseconds between captures |
| maxLogs | 10 | Maximum stored console logs |
| maxErrors | 10 | Maximum stored error logs |
| autoConnect | true | Connect on initialization |
| canvasId | null | ID of specific canvas to capture (null = auto-detect) |
| debugWindow | Object | Configuration for the debug window (see below) |

### SVG Display Options

| Option | Default | Description |
|--------|---------|-------------|
| container | null | Element or selector for SVG container (creates popup window if null) |

### Debug Window Options

| Option | Default | Description |
|--------|---------|-------------|
| width | null | Width of the debug window in pixels (null = 75% of game window width) |
| height | null | Height of the debug window in pixels (null = 75% of game window height) |
| position | 'right' | Position relative to the game window: 'right', 'left', 'top', 'bottom', or 'detached' |

## Build Formats

The following build formats are available in the `dist/` directory:

- `vibe-eyes.min.js` - Minified UMD build for most use cases
- `vibe-eyes.js` - Unminified UMD build for debugging
- `vibe-eyes.iife.js` - IIFE build with globals for direct browser use
- `vibe-eyes.esm.js` - ES Module for modern bundlers and environments

## Related Projects

- [Vibe Eyes MCP Server](https://github.com/monteslu/vibe-eyes) - The companion server that processes debug data and generates visualizations

## License

ISC