npm package: @jiweiyuan/runbrowser-server
Description: RunBrowser server — bridges Chrome extension WebSocket to CDP clients
Latest version: 0.0.6

# @jiweiyuan/runbrowser-server

CDP (Chrome DevTools Protocol) relay server for [RunBrowser](https://github.com/runbrowser/runbrowser). This package bridges Chrome extension WebSocket connections to Playwright CDP clients, enabling browser automation over your running Chrome browser.

## Architecture

```
┌──────────────┐     WebSocket      ┌─────────────────┐     WebSocket      ┌────────────────┐
│   Chrome     │ ◄─────────────────►│  Relay Server   │ ◄─────────────────►│   Playwright   │
│  Extension   │    /extension      │  (this package)  │    /cdp/:clientId  │  CDP Client    │
└──────────────┘                    └─────────────────┘                    └────────────────┘
                                          │
                                          │  HTTP API
                                          │  /version, /json, /extension/status
                                          │  /cli/*, /recording/*
                                          ▼
```

The relay server:
- Accepts WebSocket connections from the RunBrowser Chrome extension
- Accepts WebSocket connections from Playwright CDP clients
- Routes CDP commands/events between them
- Manages extension connections, target tracking, and session state
- Provides HTTP endpoints for discovery, status, CLI execution, and recording

## Installation

```bash
npm install @jiweiyuan/runbrowser-server
```

## Usage

### Programmatic

```ts
import { startRunBrowserCDPRelayServer } from '@jiweiyuan/runbrowser-server'

const server = await startRunBrowserCDPRelayServer({
  port: 19988,
  host: '127.0.0.1',
  logger: console,
})

// Later...
server.close()
```

### With CLI Execute Endpoints

To enable `/cli/*` endpoints, provide an executor manager factory:

```ts
import { startRunBrowserCDPRelayServer } from '@jiweiyuan/runbrowser-server'

const server = await startRunBrowserCDPRelayServer({
  port: 19988,
  executorManagerFactory: async ({ cdpConfig, logger }) => {
    const { ExecutorManager } = await import('runbrowser/executor')
    return new ExecutorManager({ cdpConfig, logger })
  },
})
```

### Standalone Binary

```bash
npx @jiweiyuan/runbrowser-server
```

## Client Utilities

The package also provides client-side utilities for connecting to the relay server:

```ts
import { ensureRelayServer, RELAY_PORT, waitForConnectedExtensions } from '@jiweiyuan/runbrowser-server/client'

// Start relay server if not running
await ensureRelayServer({ logger: console })

// Wait for Chrome extension to connect
const extensions = await waitForConnectedExtensions({
  timeoutMs: 10000,
  logger: console,
})
```

## Exports

| Subpath | Description |
|---------|-------------|
| `@jiweiyuan/runbrowser-server` | Core server, state management, types, utilities |
| `@jiweiyuan/runbrowser-server/client` | Client utilities (ensureRelayServer, version checks) |
| `@jiweiyuan/runbrowser-server/types` | CDP protocol types |
| `@jiweiyuan/runbrowser-server/protocol` | Extension message protocol types |
| `@jiweiyuan/runbrowser-server/utils` | Shared utilities (EXTENSION_IDS, VERSION, log paths) |
| `@jiweiyuan/runbrowser-server/logger` | File logger |

## Key Types

```ts
// Server configuration
interface RelayServer {
  close(): void
  on<K extends keyof RelayServerEvents>(event: K, listener: RelayServerEvents[K]): void
  off<K extends keyof RelayServerEvents>(event: K, listener: RelayServerEvents[K]): void
}

// Executor dependency injection (for CLI endpoints)
interface ExecutorManagerLike { ... }
interface ExecutorLike { ... }
type ExecutorManagerFactory = (config: { cdpConfig, logger }) => Promise<ExecutorManagerLike>

// Relay state
interface ExtensionEntry { id, info, stableKey, connectedTargets, ws, ... }
interface PlaywrightClient { id, extensionId, ws }
interface RelayState { extensions, playwrightClients }
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `RUNBROWSER_PORT` | Relay server port (default: 19988) |
| `RUNBROWSER_AUTO_ENABLE` | Auto-create initial tab for Playwright |
| `RUNBROWSER_LOG_FILE_PATH` | Custom relay server log path |
| `RUNBROWSER_CDP_LOG_FILE_PATH` | Custom CDP log path |

## License

MIT