@askjo/camofox-browser 1.5.1 → 1.6.0

package/plugin.ts

@@ -399,6 +399,13 @@ export default function register(api: PluginApi) {
         const text = await res.text();
         throw new Error(`${res.status}: ${text}`);
       }
+      // Guard: if server returns JSON/text instead of image (e.g. error with 200),
+      // return as text to avoid crashing the client with base64-encoded JSON.
+      const contentType = res.headers.get('content-type') || '';
+      if (!contentType.startsWith('image/')) {
+        const text = await res.text();
+        return { content: [{ type: "text", text: `Screenshot failed: ${text}` }] };
+      }
       const arrayBuffer = await res.arrayBuffer();
       const base64 = Buffer.from(arrayBuffer).toString("base64");
       return {
@@ -406,7 +413,7 @@ export default function register(api: PluginApi) {
           {
             type: "image",
             data: base64,
-            mimeType: "image/png",
+            mimeType: contentType || "image/png",
           },
         ],
       };

package/plugins/persistence/AGENTS.md

@@ -0,0 +1,37 @@
+# Persistence Plugin — Agent Guide
+
+Saves and restores per-user browser storage state (cookies + localStorage) across session restarts using Playwright's `storageState` API. Enabled by default — profiles persist to `~/.camofox/profiles/`.
+
+## How It Works
+
+- `session:creating` hook → loads saved `storage_state.json` into `contextOptions.storageState`
+- `session:created` hook → imports bootstrap cookies if no persisted state exists
+- `session:cookies:import` / `session:destroyed` / `server:shutdown` → checkpoints state to disk
+
+All hooks are async and awaited via `emitAsync()` — storage state is guaranteed loaded before the context is created.
+
+## Key Files
+
+- `index.js` — lifecycle hooks (no routes, no `child_process`)
+- `persistence.test.js` — unit tests for `lib/persistence.js` helpers
+- `plugin.test.js` — integration tests for plugin lifecycle hooks
+
+## Storage Layout
+
+```
+~/.camofox/profiles/
+└── <sha256(userId)>/
+    └── storage_state.json
+```
+
+## Configuration
+
+Enabled by default. Override profile directory with `CAMOFOX_PROFILE_DIR` env var or `"profileDir"` in plugin config. To disable: `"persistence": { "enabled": false }` in `camofox.config.json`.
+
+## Original Contributors
+
+- [@company8](https://github.com/company8) — original persistence concept ([PR #62](https://github.com/jo-inc/camofox-browser/pull/62))
+- [@eddieoz](https://github.com/eddieoz) — cookie auto-load on startup ([PR #55](https://github.com/jo-inc/camofox-browser/pull/55))
+- [@pradeepe](https://github.com/pradeepe) — plugin system integration, atomic writes, inflight coalescing
+
+For PRs touching this plugin, tag the contributors above for review.

package/plugins/persistence/README.md

@@ -0,0 +1,48 @@
+# persistence
+
+Optional per-user browser storage state persistence for camofox-browser.
+
+Saves and restores cookies + localStorage across session restarts, container deploys, and idle timeouts using Playwright's `storageState` API.
+
+## Configuration
+
+In `camofox.config.json`:
+
+```json
+{
+  "plugins": {
+    "persistence": {
+      "enabled": true,
+      "profileDir": "/data/profiles"
+    }
+  }
+}
+```
+
+Or override via environment variable:
+
+```
+CAMOFOX_PROFILE_DIR=/data/profiles
+```
+
+## How it works
+
+- **Session create**: If a persisted `storageState` exists for the `userId`, it's restored into the new Playwright context.
+- **First run**: If no persisted state exists, bootstrap cookies from `CAMOFOX_COOKIES_DIR/cookies.txt` are imported (if present).
+- **Cookie import / session close / shutdown**: Storage state is checkpointed to disk via atomic tmp-write + rename.
+- **User isolation**: Each `userId` maps to a deterministic SHA256-hashed subdirectory under `profileDir`, so arbitrary userIds are path-safe.
+
+## Docker
+
+When running with Docker, mount the profile directory as a volume:
+
+```bash
+docker run -d \
+  -p 9377:9377 \
+  -v /host/profiles:/data/profiles \
+  camofox-browser
+```
+
+## Credits
+
+Based on PR #62 by [company8](https://github.com/company8).

package/plugins/persistence/index.js

@@ -0,0 +1,120 @@
+/**
+ * Persistence plugin for camofox-browser.
+ *
+ * Saves and restores per-user browser storage state (cookies + localStorage)
+ * across session restarts using Playwright's storageState API.
+ *
+ * Configuration (camofox.config.json):
+ *   {
+ *     "plugins": {
+ *       "persistence": {
+ *         "enabled": true,
+ *         "profileDir": "/data/profiles"
+ *       }
+ *     }
+ *   }
+ *
+ * Or via environment variables (overrides config file):
+ *   CAMOFOX_PROFILE_DIR=/data/profiles
+ *
+ * Each userId gets a deterministic SHA256-hashed subdirectory under profileDir.
+ * Storage state is checkpointed on cookie import, session close, and shutdown.
+ * On session creation, saved state is restored into the new Playwright context
+ * via the session:creating hook (mutates contextOptions.storageState).
+ */
+
+import {
+  getUserPersistencePaths,
+  loadPersistedStorageState,
+  persistStorageState,
+} from '../../lib/persistence.js';
+import { importBootstrapCookies } from '../../lib/cookies.js';
+
+export async function register(app, ctx, pluginConfig = {}) {
+  const { events, config, log } = ctx;
+
+  // Resolve profileDir: env var > plugin config > global config default (~/.camofox/profiles)
+  const profileDir = process.env.CAMOFOX_PROFILE_DIR || pluginConfig.profileDir || config.profileDir;
+  if (!profileDir) {
+    log('warn', 'persistence plugin: no profileDir configured, plugin disabled');
+    return;
+  }
+
+  const logger = {
+    warn: (msg, fields = {}) => log('warn', msg, fields),
+  };
+
+  log('info', 'persistence plugin enabled', { profileDir });
+
+  // Track active sessions for checkpoint on close
+  const activeSessions = new Map(); // userId -> context
+
+  /**
+   * Checkpoint storage state to disk for a userId.
+   */
+  async function checkpoint(userId, context, reason) {
+    if (!context) return;
+    const result = await persistStorageState({ profileDir, userId, context, logger });
+    if (result.persisted) {
+      log('info', 'storage state persisted', { userId, reason, path: result.storageStatePath });
+    }
+    return result;
+  }
+
+  // --- Lifecycle hooks ---
+
+  // Before session context is created: inject storageState if we have one saved
+  events.on('session:creating', async ({ userId, contextOptions }) => {
+    const storageStatePath = await loadPersistedStorageState(profileDir, userId, logger);
+    if (storageStatePath) {
+      contextOptions.storageState = storageStatePath;
+      log('info', 'restoring persisted storage state', { userId, storageStatePath });
+    }
+  });
+
+  // After session is created: import bootstrap cookies if no persisted state,
+  // and track the context for later checkpointing
+  events.on('session:created', async ({ userId, context }) => {
+    activeSessions.set(userId, context);
+
+    // If no persisted state was restored, try bootstrap cookies
+    const existingState = await loadPersistedStorageState(profileDir, userId, logger);
+    if (!existingState) {
+      const result = await importBootstrapCookies({
+        cookiesDir: config.cookiesDir,
+        context,
+        logger,
+      });
+      if (result.imported > 0) {
+        log('info', 'bootstrap cookies imported', { userId, count: result.imported, source: result.source });
+        await checkpoint(userId, context, 'bootstrap_cookies');
+      }
+    }
+  });
+
+  // On cookie import: checkpoint
+  events.on('session:cookies:import', async ({ userId }) => {
+    const context = activeSessions.get(userId);
+    if (context) {
+      await checkpoint(userId, context, 'cookie_import');
+    }
+  });
+
+  // On session destroy: checkpoint then remove from tracking
+  events.on('session:destroyed', async ({ userId, reason }) => {
+    const context = activeSessions.get(userId);
+    if (context) {
+      // Context may already be closed — checkpoint will fail gracefully
+      await checkpoint(userId, context, reason).catch(() => {});
+      activeSessions.delete(userId);
+    }
+  });
+
+  // On shutdown: checkpoint all remaining sessions
+  events.on('server:shutdown', async () => {
+    for (const [userId, context] of activeSessions) {
+      await checkpoint(userId, context, 'shutdown').catch(() => {});
+    }
+    activeSessions.clear();
+  });
+}

package/plugins/persistence/persistence.test.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { jest } from '@jest/globals';
+import {
+  getUserPersistencePaths,
+  loadPersistedStorageState,
+  persistStorageState,
+} from '../../lib/persistence.js';
+
+describe('profile persistence helpers', () => {
+  let tmpDir;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'camofox-persistence-'));
+  });
+
+  afterEach(async () => {
+    if (tmpDir) {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test('getUserPersistencePaths is deterministic and stays under root', () => {
+    const first = getUserPersistencePaths(tmpDir, 'agent/profile:default');
+    const second = getUserPersistencePaths(tmpDir, 'agent/profile:default');
+
+    expect(first).toEqual(second);
+    expect(first.userDir.startsWith(tmpDir)).toBe(true);
+    expect(first.storageStatePath.startsWith(first.userDir)).toBe(true);
+    expect(first.metaPath.startsWith(first.userDir)).toBe(true);
+    expect(path.basename(first.userDir)).not.toContain('/');
+    expect(path.basename(first.userDir)).not.toContain(':');
+  });
+
+  test('loadPersistedStorageState returns undefined when no state exists', async () => {
+    await expect(loadPersistedStorageState(tmpDir, 'user-1')).resolves.toBeUndefined();
+  });
+
+  test('persistStorageState writes storage state and metadata, then load returns the storage path', async () => {
+    const storageState = {
+      cookies: [{ name: 'session', value: 'abc', domain: '.example.com', path: '/' }],
+      origins: [{ origin: 'https://app.example.com', localStorage: [{ name: 'foo', value: 'bar' }] }],
+    };
+
+    const context = {
+      storageState: jest.fn(async ({ path: targetPath }) => {
+        await fs.writeFile(targetPath, JSON.stringify(storageState, null, 2));
+      }),
+    };
+
+    const result = await persistStorageState({
+      profileDir: tmpDir,
+      userId: 'user-1',
+      context,
+      logger: { warn: jest.fn() },
+    });
+
+    expect(result.persisted).toBe(true);
+    expect(context.storageState).toHaveBeenCalledTimes(1);
+
+    const loadedPath = await loadPersistedStorageState(tmpDir, 'user-1');
+    expect(loadedPath).toBe(result.storageStatePath);
+
+    const meta = JSON.parse(await fs.readFile(result.metaPath, 'utf8'));
+    expect(meta.userId).toBe('user-1');
+    expect(meta.storageStatePath).toBe(result.storageStatePath);
+  });
+
+  test('loadPersistedStorageState ignores invalid JSON files', async () => {
+    const { storageStatePath } = getUserPersistencePaths(tmpDir, 'user-2');
+    await fs.mkdir(path.dirname(storageStatePath), { recursive: true });
+    await fs.writeFile(storageStatePath, '{not-json');
+
+    await expect(loadPersistedStorageState(tmpDir, 'user-2', { warn: jest.fn() })).resolves.toBeUndefined();
+  });
+
+  test('a failed persist leaves the previous storage-state intact and cleans up tmp files', async () => {
+    const originalState = {
+      cookies: [{ name: 'orig', value: 'v1', domain: '.example.com', path: '/' }],
+    };
+    const goodContext = {
+      storageState: jest.fn(async ({ path: targetPath }) => {
+        await fs.writeFile(targetPath, JSON.stringify(originalState, null, 2));
+      }),
+    };
+    const first = await persistStorageState({
+      profileDir: tmpDir,
+      userId: 'user-3',
+      context: goodContext,
+      logger: { warn: jest.fn() },
+    });
+    expect(first.persisted).toBe(true);
+
+    const failingContext = {
+      storageState: jest.fn(async () => {
+        throw new Error('simulated crash mid-write');
+      }),
+    };
+    const second = await persistStorageState({
+      profileDir: tmpDir,
+      userId: 'user-3',
+      context: failingContext,
+      logger: { warn: jest.fn() },
+    });
+    expect(second.persisted).toBe(false);
+
+    const { userDir, storageStatePath } = getUserPersistencePaths(tmpDir, 'user-3');
+    const loaded = await loadPersistedStorageState(tmpDir, 'user-3');
+    expect(loaded).toBe(storageStatePath);
+    const parsed = JSON.parse(await fs.readFile(storageStatePath, 'utf8'));
+    expect(parsed).toEqual(originalState);
+
+    const leftovers = (await fs.readdir(userDir)).filter((name) => name.includes('.tmp-'));
+    expect(leftovers).toEqual([]);
+  });
+});

package/plugins/persistence/plugin.test.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { jest } from '@jest/globals';
+import { createPluginEvents } from '../../lib/plugins.js';
+import { register } from './index.js';
+
+describe('persistence plugin', () => {
+  let tmpDir, events, ctx, mockApp;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'camofox-persist-plugin-'));
+    events = createPluginEvents();
+    mockApp = {};
+    ctx = {
+      events,
+      config: { cookiesDir: path.join(tmpDir, 'cookies') },
+      log: jest.fn(),
+    };
+  });
+
+  afterEach(async () => {
+    if (tmpDir) await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test('skips registration when no profileDir configured', async () => {
+    await register(mockApp, ctx, {});
+    expect(ctx.log).toHaveBeenCalledWith('warn', expect.stringContaining('no profileDir'));
+  });
+
+  test('restores persisted state on session:creating', async () => {
+    await register(mockApp, ctx, { profileDir: tmpDir });
+
+    // Simulate a prior persisted state
+    const { getUserPersistencePaths } = await import('../../lib/persistence.js');
+    const { userDir, storageStatePath } = getUserPersistencePaths(tmpDir, 'user-1');
+    await fs.mkdir(userDir, { recursive: true });
+    await fs.writeFile(storageStatePath, JSON.stringify({
+      cookies: [{ name: 'sid', value: 'abc', domain: '.example.com', path: '/' }],
+      origins: [],
+    }));
+
+    const contextOptions = { viewport: { width: 1280, height: 720 } };
+    await events.emitAsync('session:creating', { userId: 'user-1', contextOptions });
+
+    expect(contextOptions.storageState).toBe(storageStatePath);
+  });
+
+  test('checkpoints on session:cookies:import', async () => {
+    await register(mockApp, ctx, { profileDir: tmpDir });
+
+    const mockContext = {
+      storageState: jest.fn(async ({ path: p }) => {
+        await fs.writeFile(p, JSON.stringify({ cookies: [{ name: 'x', value: 'y', domain: '.test.com', path: '/' }] }));
+      }),
+    };
+
+    // Simulate session created then cookie import
+    await events.emitAsync('session:created', { userId: 'user-2', context: mockContext });
+    await events.emitAsync('session:cookies:import', { userId: 'user-2' });
+
+    expect(mockContext.storageState).toHaveBeenCalled();
+
+    // Verify file was written
+    const { getUserPersistencePaths } = await import('../../lib/persistence.js');
+    const { storageStatePath } = getUserPersistencePaths(tmpDir, 'user-2');
+    const saved = JSON.parse(await fs.readFile(storageStatePath, 'utf8'));
+    expect(saved.cookies[0].name).toBe('x');
+  });
+
+  test('checkpoints on session:destroyed', async () => {
+    await register(mockApp, ctx, { profileDir: tmpDir });
+
+    const mockContext = {
+      storageState: jest.fn(async ({ path: p }) => {
+        await fs.writeFile(p, JSON.stringify({ cookies: [], origins: [] }));
+      }),
+    };
+
+    await events.emitAsync('session:created', { userId: 'user-3', context: mockContext });
+    await events.emitAsync('session:destroyed', { userId: 'user-3', reason: 'test' });
+
+    expect(mockContext.storageState).toHaveBeenCalled();
+  });
+
+  test('env var CAMOFOX_PROFILE_DIR overrides pluginConfig', async () => {
+    const envDir = path.join(tmpDir, 'env-override');
+    const orig = process.env.CAMOFOX_PROFILE_DIR;
+    process.env.CAMOFOX_PROFILE_DIR = envDir;
+    try {
+      await register(mockApp, ctx, { profileDir: '/should/not/use' });
+      expect(ctx.log).toHaveBeenCalledWith('info', 'persistence plugin enabled', { profileDir: envDir });
+    } finally {
+      if (orig === undefined) delete process.env.CAMOFOX_PROFILE_DIR;
+      else process.env.CAMOFOX_PROFILE_DIR = orig;
+    }
+  });
+});

package/plugins/vnc/AGENTS.md

@@ -0,0 +1,42 @@
+# VNC Plugin — Agent Guide
+
+Interactive browser access via noVNC. Log into sites visually, solve CAPTCHAs, approve OAuth prompts — then export the authenticated storage state for agent reuse.
+
+## Endpoints
+
+- `GET /vnc/status` — check if VNC is running (no auth)
+- `GET /sessions/:userId/storage_state` — export cookies + localStorage as JSON (requires auth)
+
+## Activation
+
+Disabled by default. Enable with `ENABLE_VNC=1` env var or `"vnc": { "enabled": true }` in `camofox.config.json`.
+
+## Key Files
+
+- `index.js` — route handlers only (no `child_process`, no `process.env` reads)
+- `vnc-launcher.js` — process management, config resolution from env vars (`child_process` isolated here)
+- `vnc-watcher.sh` — shell script that detects Xvfb, attaches x11vnc, starts noVNC
+- `vnc.test.js` — unit tests
+- `apt.txt` — system deps (x11vnc, novnc, websockify, etc.)
+
+## Scanner Compliance
+
+`child_process` is in `vnc-launcher.js`, route handlers are in `index.js`, env var reads are in `vnc-launcher.js` — separate files per OpenClaw scanner rules.
+
+## Security
+
+- noVNC binds to `127.0.0.1` by default — set `VNC_BIND=0.0.0.0` to expose externally
+- Set `VNC_PASSWORD` for password-protected access
+- `VIEW_ONLY=1` disables keyboard/mouse input (observation only)
+- Storage state export endpoint requires auth (API key or loopback)
+
+## Architecture
+
+The plugin overrides `ctx.createVirtualDisplay` to use a higher-resolution display (default 1920x1080 instead of 1x1). `vnc-watcher.sh` polls for the Xvfb process, then attaches x11vnc + noVNC on top.
+
+## Original Contributors
+
+- [@leoneparise](https://github.com/leoneparise) — original VNC implementation + keyboard mode ([PR #65](https://github.com/jo-inc/camofox-browser/pull/65), [PR #66](https://github.com/jo-inc/camofox-browser/pull/66))
+- [@pradeepe](https://github.com/pradeepe) — plugin system integration, scanner compliance refactor, security hardening
+
+For PRs touching this plugin, tag the contributors above for review.

package/plugins/vnc/README.md

@@ -0,0 +1,165 @@
+# VNC Plugin
+
+> Originally contributed by [@leoneparise](https://github.com/leoneparise) in [PR #65](https://github.com/jo-inc/camofox-browser/pull/65). Reworked as a plugin for the camofox extension system.
+
+Interactive browser access via VNC. Log into sites visually, solve CAPTCHAs, approve OAuth prompts — then export the authenticated storage state for reuse by your agent.
+
+## How it works
+
+```
+Camoufox (Xvfb :99, 1920x1080)
+    ↑
+x11vnc (attaches to :99, port 5900)
+    ↑
+noVNC / websockify (port 6080)
+    ↑
+Your browser → http://localhost:6080/vnc.html
+```
+
+The plugin overrides Camoufox's default 1x1 virtual display with a human-usable resolution, then runs a watcher process that detects the Xvfb display and attaches x11vnc + noVNC. The watcher handles browser restarts automatically — when Camoufox relaunches on a new display, x11vnc reattaches.
+
+## Quick start
+
+### Docker
+
+```bash
+docker run -p 9377:9377 -p 6080:6080 \
+  -e ENABLE_VNC=1 \
+  camofox-browser
+
+# Open http://localhost:6080/vnc.html in your browser
+```
+
+### Config file
+
+```json
+{
+  "plugins": {
+    "vnc": {
+      "enabled": true,
+      "resolution": "1920x1080",
+      "password": "optional-secret",
+      "viewOnly": false,
+      "novncPort": 6080
+    }
+  }
+}
+```
+
+## Workflow: interactive login → agent reuse
+
+1. **Start with VNC enabled:**
+   ```bash
+   docker run -p 9377:9377 -p 6080:6080 -e ENABLE_VNC=1 camofox-browser
+   ```
+
+2. **Create a session and navigate to the login page:**
+   ```bash
+   curl -X POST http://localhost:9377/tabs \
+     -H 'Content-Type: application/json' \
+     -d '{"userId": "my-agent", "sessionKey": "default", "url": "https://accounts.google.com"}'
+   ```
+
+3. **Log in visually** via http://localhost:6080/vnc.html — complete MFA, solve CAPTCHAs, etc.
+
+4. **Export the authenticated state:**
+   ```bash
+   curl http://localhost:9377/sessions/my-agent/storage_state \
+     -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \
+     -o storage_state.json
+   ```
+
+5. **Reuse on future runs** — pair with the [persistence plugin](../persistence/) to automatically restore state on session creation:
+   ```json
+   {
+     "plugins": {
+       "vnc": { "enabled": true },
+       "persistence": { "enabled": true, "profileDir": "/data/profiles" }
+     }
+   }
+   ```
+   With both plugins active, the persistence plugin automatically checkpoints storage state on session close and restores it on creation. The VNC plugin's export endpoint also triggers a persistence checkpoint via the `session:storage:export` event.
+
+## API
+
+### GET /sessions/:userId/storage_state
+
+Export the full Playwright storage state (cookies + localStorage origins) for a user's active browser context.
+
+**Auth:** Same as cookie import — requires `CAMOFOX_API_KEY` Bearer token, or loopback access in non-production.
+
+**Response:**
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": ".example.com",
+      "path": "/",
+      "expires": 1700000000,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" }
+      ]
+    }
+  ]
+}
+```
+
+**Errors:**
+- `404` — No active session for the given userId
+- `403` — Missing or invalid API key
+- `500` — Context is dead or storageState export failed
+
+## Configuration
+
+| Source | Variable | Description | Default |
+|--------|----------|-------------|---------|
+| env | `ENABLE_VNC` | Enable the plugin (`1`) | off |
+| env | `VNC_PASSWORD` | x11vnc password | none (open) |
+| env | `VNC_RESOLUTION` | Xvfb screen resolution | `1920x1080` |
+| env | `VIEW_ONLY` | Disable mouse/keyboard input (`1`) | off |
+| env | `VNC_PORT` | x11vnc listen port | `5900` |
+| env | `NOVNC_PORT` | noVNC web UI port | `6080` |
+| config | `plugins.vnc.enabled` | Enable the plugin | `false` |
+| config | `plugins.vnc.password` | x11vnc password | none |
+| config | `plugins.vnc.resolution` | Xvfb screen resolution | `1920x1080` |
+| config | `plugins.vnc.viewOnly` | View-only mode | `false` |
+| config | `plugins.vnc.vncPort` | x11vnc listen port | `5900` |
+| config | `plugins.vnc.novncPort` | noVNC web UI port | `6080` |
+
+Environment variables override config file values.
+
+## Security
+
+⚠️ **VNC is unencrypted by default.** When running in production:
+
+- **Set `VNC_PASSWORD`** — without it, anyone who can reach port 6080 has full browser control
+- **Bind 6080 to localhost** and access via SSH tunnel: `ssh -L 6080:localhost:6080 your-server`
+- **Or use a firewall** to restrict access to port 6080
+- In Docker: `-p 127.0.0.1:6080:6080` binds only to localhost
+
+## System dependencies
+
+The plugin declares its apt dependencies in `apt.txt` — these are installed automatically during `docker build` via `scripts/install-plugin-deps.sh`:
+
+- `x11vnc` — attaches to Xvfb display
+- `novnc` + `python3-websockify` — web-based VNC client
+- `net-tools` + `procps` — display detection utilities
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `vnc:watcher:started` | `{ pid }` | Watcher process spawned |
+| `vnc:watcher:stopped` | `{ code, signal }` | Watcher exited |
+| `vnc:storage:exported` | `{ userId, cookies, origins }` | Storage state exported via API |
+| `session:storage:export` | `{ userId }` | Emitted after export (persistence plugin listens) |

package/plugins/vnc/apt.txt

@@ -0,0 +1,7 @@
+# VNC stack: x11vnc attaches to Camoufox's Xvfb, noVNC + websockify expose it over HTTP
+x11vnc
+novnc
+python3-websockify
+# Utilities for display detection
+net-tools
+procps