Vibe Eyes Client

A lightweight client library to integrate browser games with the Vibe Eyes MCP debug server for real-time debugging, visualization, and analysis.

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

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

npm install vibe-eyes-client

Or include directly in your HTML:

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

Usage

Basic Integration

// 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

// 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

// 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:

// 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

SVG Display Options

Debug Window Options

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 - The companion server that processes debug data and generates visualizations

License

ISC