@acertijosapps/electron-viewer 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 AcertijosApps
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# @acertijosapps/electron-viewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Live viewer for Electron apps in the browser, plus an MCP server so an AI agent can drive them.
+Built for the browser pane of AI coding tools (such as Claude Code): you and the agent watch and
+control the same app window, in real time.
+
+<img src="https://unpkg.com/@acertijosapps/electron-viewer/media/viewer.jpg" width="560" alt="Electron Viewer showing the example app: window selector and launch button on top, the live window in the middle, and the reload, DevTools, window size, frame and screenshot controls at the bottom" />
+
+- **Live video**: `Page.startScreencast` from the Chrome DevTools Protocol (CDP) over WebSocket. It keeps
+  streaming while the app window is covered or minimized.
+- **Real input**: mouse move and hover, click, double click, right click, drag, wheel and full keyboard
+  passthrough (including ⌘C/⌘V/⌘A on macOS, IME and dictation).
+- **Every app and window**: launch your project with `electron .` from the viewer, or attach to any app
+  started with `--remote-debugging-port`. Apps on ports 9222–9231 are found automatically.
+- **Main process too**: launched apps also expose their main process (Node inspector), so the agent can
+  run code there, resize the real window, open DevTools and capture the native frame.
+- **Native frame capture**: title bar, context menus and dialogs on top of the window.
+- **MCP server**: the same actions as tools, plus JavaScript in the renderer and main process, the
+  accessibility tree with click-ready coordinates, and console logs.
+- **Nothing to add to your app**: no preload, no dependency, no code changes.
+
+## Requirements
+
+- Node.js 18 or later.
+- An Electron app. To launch it from the viewer, the project must have `electron` in its
+  `node_modules` (`npm install --save-dev electron`); if its binary hasn't been downloaded yet, the
+  viewer downloads it on the first launch.
+- Works on macOS, Linux and Windows.
+
+## Quick start
+
+From your Electron project folder:
+
+```sh
+npx @acertijosapps/electron-viewer
+```
+
+Open <http://localhost:8094> and click **Launch**. The viewer runs `electron .` on free debugging
+ports (CDP from 9222, Node inspector from 9229). Deep link to a window: `?window=<target id>`.
+
+If your app is started by another tool (Electron Forge, electron-vite, a custom script), pass the flags
+yourself and the viewer finds it:
+
+```sh
+electron --remote-debugging-port=9222 --inspect=9229 .
+```
+
+`--inspect` is optional; without it you get everything except the main-process features
+(`evaluate_main`, frame capture, real window resizing and in-app DevTools). To attach on another
+port, use the form in the viewer or `--attach`.
+
+```text
+electron-viewer [options]        Start the viewer
+electron-viewer mcp [options]    Start the MCP server on stdio
+
+      --project <dir>      Project to launch with "electron ." (default: current folder)
+  -p, --port <port>        Viewer port (default 8094, env PORT)
+      --host <host>        Interface to bind (default 127.0.0.1, env HOST)
+      --attach <port>      Attach at startup to an app on this CDP port
+      --inspect <port>     With --attach: the app's main process inspector port
+      --viewer-url <url>   Viewer the MCP talks to (default http://localhost:8094)
+```
+
+Other environment variables: `MAX_DIM` (longest side of the streamed frames, default 1920), `QUALITY`
+(JPEG quality, default 80), `SCREENSHOT_MAX` (longest side of MCP screenshots, default 1024),
+`CDP_PORT` / `INSPECT_PORT` (first ports to scan and launch on, default 9222 / 9229) and
+`ELECTRON_VIEWER_STATE_DIR` (where launched and attached apps are remembered, default
+`~/.cache/electron-viewer`).
+
+## Use it with an AI agent (MCP)
+
+Claude Code:
+
+```sh
+claude mcp add electron-viewer -- npx -y @acertijosapps/electron-viewer mcp
+```
+
+Any other MCP client:
+
+```json
+{
+  "mcpServers": {
+    "electron-viewer": {
+      "command": "npx",
+      "args": ["-y", "@acertijosapps/electron-viewer", "mcp"]
+    }
+  }
+}
+```
+
+Also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.acertijosapps/electron-viewer`.
+
+Keep the viewer running (`npx @acertijosapps/electron-viewer`) to watch what the agent does. Without
+it, the MCP drives the app over CDP directly. Apps launched by either one are visible to the other.
+
+| Tool | What it does |
+| --- | --- |
+| `list_windows` | Running apps (with `main` when the main process is reachable) and their windows |
+| `launch_app` | Run `electron .` in the project on free debugging ports and wait for the first window |
+| `attach` | Attach to an app on a CDP port, optionally with its inspector port |
+| `screenshot` | PNG of the window content, longest side ≤ 1024 px; `frame: true` adds the native frame, menus and dialogs |
+| `click` | Left, right or middle click; `count: 2` for a double click; optional modifiers |
+| `drag` | Press, move in steps and release: a real drag |
+| `hover` | Move the mouse without clicking |
+| `scroll` | Mouse wheel at a point, deltas in CSS px |
+| `type_text` | Insert text into the focused element (any Unicode) |
+| `press_key` | Enter, Tab, Escape, arrows, F1–F12… or any character, with modifiers |
+| `resize_window` | Resize the content area (the real window with the main process, emulated without it) |
+| `reload` | Reload the window's page |
+| `evaluate` | Run JavaScript in the window's page and return the value |
+| `evaluate_main` | Run JavaScript in the main process, with `require('electron')` available |
+| `get_accessibility_tree` | Roles, names, values and states; interactive elements carry their normalized center |
+| `get_console_logs` | Console messages and exceptions from renderer windows and the main process, or the raw stdout |
+
+Coordinates are normalized to `0–1` over the content screenshot (`x = pixel_x / image_width`), so they
+hold at any window size. `window` is optional when only one window is open; it takes the target id
+from `list_windows` or part of the window title.
+
+### In the Claude Code browser pane
+
+Add the viewer to `.claude/launch.json` and open it with `preview_start electron-viewer`:
+
+```json
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "electron-viewer",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["-y", "@acertijosapps/electron-viewer"],
+      "port": 8094,
+      "autoPort": false
+    }
+  ]
+}
+```
+
+## Native frame capture
+
+The **frame** button (and `screenshot` with `frame: true`) captures the screen area of the window from
+the main process with `desktopCapturer`: the title bar, native context menus and dialogs on top of the
+window show up, at a few frames per second. Anything else covering the window shows up too, and the
+macOS menu bar at the top of the screen is not included. In frame mode, clicks on the content still
+work; the title bar and native menus can't be clicked from the viewer.
+
+On macOS the app needs the **Screen Recording** permission (System Settings › Privacy & Security ›
+Screen & System Audio Recording). For an app run with `electron .`, that is the `Electron.app` inside
+the project's `node_modules/electron/dist`; the error message gives the exact path. Restart the app
+after allowing it.
+
+## HTTP API
+
+The MCP uses the viewer's API; you can call it too. `window` (target id or part of the title) goes in
+the query string or the body and is optional with a single window. The server only listens on
+127.0.0.1, only accepts a local `Host` and origin, and `POST` requests require
+`content-type: application/json`, so other websites can't drive your apps.
+
+| Endpoint | |
+| --- | --- |
+| `GET /api/windows` | `[{ id, name, cdpPort, inspectPort, main, windows: [{ id, title, url }] }]` |
+| `GET /api/project` | The project the viewer launches and whether it has Electron installed |
+| `GET /api/screenshot?max=<px>&frame=1` | PNG; viewport size in `X-Viewport-Width` / `X-Viewport-Height` |
+| `GET /api/ax-tree?interactiveOnly=true` | `{ tree }` |
+| `GET /api/logs?level=&source=&limit=` | `{ logs }` or `{ stdout }` |
+| `POST /api/launch` | `{ project? }` |
+| `POST /api/attach` | `{ port, inspectPort? }` |
+| `POST /api/click` | `{ x, y, button?, count?, modifiers? }` |
+| `POST /api/drag` | `{ x1, y1, x2, y2, ms? }` |
+| `POST /api/hover` | `{ x, y }` |
+| `POST /api/scroll` | `{ x, y, dx, dy }` |
+| `POST /api/text` | `{ text }` |
+| `POST /api/key` | `{ key, modifiers? }` |
+| `POST /api/resize` | `{ width, height }` (0 × 0 restores the window size) |
+| `POST /api/reload` | `{ ignoreCache? }` |
+| `POST /api/evaluate` | `{ expression }` |
+| `POST /api/evaluate-main` | `{ expression, app? }` |
+| `POST /api/devtools` | Toggles DevTools; without the main process returns the DevTools `url` |
+
+## How it works
+
+- Everything goes through CDP with `ws`: no Playwright, no Puppeteer, nothing injected into the app.
+  The renderer is reached through `--remote-debugging-port` (one `page` target per window) and the
+  main process through the Node inspector (`--inspect`), where the console API provides `require`.
+- One screencast session per window, shared by every viewer tab and stopped when the last one closes.
+  The last frame is kept for late joiners. Focus and page lifecycle are emulated while someone is
+  watching, so a covered or minimized window keeps painting.
+- Viewer input is queued in order and mouse moves are coalesced to one per animation frame. A hidden
+  textarea holds the focus: keys are sent with `Input.dispatchKeyEvent`, and text that arrives without
+  key events (IME, dictation) with `Input.insertText`. On macOS, ⌘A, ⌘C, ⌘V, ⌘X and ⌘Z are sent as
+  editing commands, because the native menu that normally handles them never sees CDP events.
+- Each process keeps one connection per window and per main process, which also collects console
+  messages and exceptions (the last 1000 per app).
+- Launched and attached apps are remembered in `~/.cache/electron-viewer`, so the viewer and the MCP see
+  the same apps. Launched apps write their output to a log file there and keep running if the viewer
+  or MCP exits.
+
+## Limitations
+
+- CDP only sees web content. Native UI (title bar, menus, dialogs, tray, notifications) is visible only
+  in frame mode and can't be clicked; use `evaluate_main` to drive it from the main process.
+- Synchronous dialogs (`dialog.showMessageBoxSync`) block the main process: `evaluate_main` and frame
+  capture wait until the dialog is closed.
+- Each `WebContentsView` is a separate CDP target, so it is listed as its own window. `<webview>` tags are
+  not listed.
+- No audio.
+- Frame mode runs at a few frames per second and, on macOS, needs the Screen Recording permission.
+- Apps that build before starting (Forge, electron-vite) can't be launched from the viewer; start them
+  with the debugging flags and they are picked up.
+
+## Contributing
+
+Branching model (`main` · `beta`), Conventional Commits and releases are described in
+[CONTRIBUTING.md](./CONTRIBUTING.md); changes are listed in [CHANGELOG.md](./CHANGELOG.md). The
+example app in [`example/`](./example) is there to try changes.
+
+## Author
+
+Made by [AcertijosApps](https://acertijosapps.com/librerias). See the rest of our libraries at
+[acertijosapps.com/librerias](https://acertijosapps.com/librerias).
+
+Questions or proposals: [acertijos.contacto@gmail.com](mailto:acertijos.contacto@gmail.com) or open an
+[issue](https://github.com/acertijosapps/electron-viewer/issues).
+
+## License
+
+MIT

package/bin/electron-viewer.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// CLI del paquete: `electron-viewer` arranca el visor; `electron-viewer mcp`, el MCP por stdio.
+
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const HELP = `electron-viewer ${version}
+
+Live viewer for Electron apps in the browser, plus an MCP server to drive them.
+
+Usage:
+  electron-viewer [options]        Start the viewer (http://localhost:8094)
+  electron-viewer mcp [options]    Start the MCP server on stdio
+
+Common options:
+      --project <dir>      Electron project to launch with "electron ." (default:
+                           current folder, env ELECTRON_VIEWER_PROJECT)
+
+Viewer options:
+  -p, --port <port>        Port to listen on (default: 8094, env PORT)
+      --host <host>        Interface to bind (default: 127.0.0.1, env HOST)
+      --attach <port>      Attach at startup to an app already running with
+                           --remote-debugging-port=<port>
+      --inspect <port>     With --attach: the app's main process inspector
+                           (--inspect=<port>), for evaluate_main, frame capture,
+                           DevTools and real window resizing
+
+MCP options:
+      --viewer-url <url>   Viewer to talk to (default: http://localhost:8094,
+                           env ELECTRON_VIEWER_URL). Without a running viewer the
+                           MCP drives the app over CDP directly.
+
+  -h, --help               Show this help
+  -v, --version            Show the version
+
+Apps are found on CDP ports 9222-9231. Launched apps get the first free CDP port
+from 9222 and inspector port from 9229.
+`;
+
+function fail(message) {
+  console.error(`electron-viewer: ${message}\nRun "electron-viewer --help" for usage.`);
+  process.exit(2);
+}
+
+const args = process.argv.slice(2);
+const command = args[0] && !args[0].startsWith('-') ? args.shift() : 'viewer';
+if (!['viewer', 'mcp'].includes(command)) fail(`unknown command "${command}"`);
+
+const portValue = (flag, v) => {
+  if (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 65535) fail(`invalid port "${v}" for ${flag}`);
+  return v;
+};
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  const [flag, inline] = arg.includes('=') ? arg.split(/=(.*)/s) : [arg];
+  const value = () => {
+    const v = inline ?? args[++i];
+    if (v === undefined || v.startsWith('-')) fail(`${flag} needs a value`);
+    return v;
+  };
+  switch (flag) {
+    case '-h':
+    case '--help':
+      process.stdout.write(HELP);
+      process.exit(0);
+      break;
+    case '-v':
+    case '--version':
+      console.log(version);
+      process.exit(0);
+      break;
+    case '-p':
+    case '--port':
+      process.env.PORT = portValue(flag, value());
+      break;
+    case '--host':
+      process.env.HOST = value();
+      break;
+    case '--project':
+      process.env.ELECTRON_VIEWER_PROJECT = path.resolve(value());
+      break;
+    case '--attach':
+      process.env.ELECTRON_VIEWER_ATTACH = portValue(flag, value());
+      break;
+    case '--inspect':
+      process.env.ELECTRON_VIEWER_INSPECT = portValue(flag, value());
+      break;
+    case '--viewer-url':
+      process.env.ELECTRON_VIEWER_URL = value();
+      break;
+    default:
+      fail(`unknown option "${arg}"`);
+  }
+}
+
+if (process.env.ELECTRON_VIEWER_INSPECT && !process.env.ELECTRON_VIEWER_ATTACH) fail('--inspect needs --attach');
+
+// Los módulos arrancan al importarse; las opciones ya quedaron en process.env.
+await import(command === 'mcp' ? '../mcp/server.js' : '../server.js');

package/lib/cdp.js

@@ -0,0 +1,112 @@
+// Cliente mínimo de Chrome DevTools Protocol sobre WebSocket. Sirve igual para un target del
+// renderer (`--remote-debugging-port`) que para el inspector de Node del proceso main (`--inspect`).
+
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+
+const CONNECT_TIMEOUT_MS = 5000;
+const COMMAND_TIMEOUT_MS = 30000;
+
+export class CdpError extends Error {}
+
+export class CdpClient extends EventEmitter {
+  static connect(wsUrl, { timeout = CONNECT_TIMEOUT_MS } = {}) {
+    return new Promise((resolve, reject) => {
+      // Sin Origin: Chromium rechaza orígenes que no estén en --remote-allow-origins.
+      const ws = new WebSocket(wsUrl, { perMessageDeflate: false, maxPayload: 256 * 1024 * 1024 });
+      const timer = setTimeout(() => {
+        ws.terminate();
+        reject(new CdpError(`Timed out connecting to ${wsUrl}`));
+      }, timeout);
+      ws.once('open', () => {
+        clearTimeout(timer);
+        resolve(new CdpClient(ws));
+      });
+      ws.once('error', (err) => {
+        clearTimeout(timer);
+        reject(new CdpError(`Could not connect to ${wsUrl}: ${err.message}`));
+      });
+    });
+  }
+
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.closed = false;
+    ws.on('message', (data) => this.onMessage(data));
+    ws.on('close', () => this.onClose());
+    ws.on('error', () => {}); // el cierre llega después por 'close'
+  }
+
+  onMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(data.toString());
+    } catch {
+      return;
+    }
+    if (msg.id) {
+      const p = this.pending.get(msg.id);
+      if (!p) return;
+      this.pending.delete(msg.id);
+      clearTimeout(p.timer);
+      if (msg.error) p.reject(new CdpError(`${p.method}: ${msg.error.message}`));
+      else p.resolve(msg.result);
+    } else if (msg.method) {
+      this.emit(msg.method, msg.params);
+      this.emit('event', msg.method, msg.params);
+    }
+  }
+
+  onClose() {
+    this.closed = true;
+    for (const p of this.pending.values()) {
+      clearTimeout(p.timer);
+      p.reject(new CdpError(`${p.method}: connection closed`));
+    }
+    this.pending.clear();
+    this.emit('close');
+  }
+
+  send(method, params = {}, { timeout = COMMAND_TIMEOUT_MS } = {}) {
+    if (this.closed) return Promise.reject(new CdpError(`${method}: connection closed`));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new CdpError(`${method}: no answer within ${timeout / 1000} s`));
+      }, timeout);
+      this.pending.set(id, { resolve, reject, timer, method });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  close() {
+    if (!this.closed) this.ws.close();
+  }
+}
+
+// GET a un endpoint HTTP del depurador (/json/list, /json/version).
+export async function fetchJson(port, route, { timeout = 1500 } = {}) {
+  const res = await fetch(`http://127.0.0.1:${port}${route}`, { signal: AbortSignal.timeout(timeout) });
+  if (!res.ok) throw new CdpError(`HTTP ${res.status} from port ${port}${route}`);
+  return res.json();
+}
+
+// Evalúa una expresión y devuelve su valor, o lanza con el mensaje de la excepción.
+export async function evaluate(client, expression, { awaitPromise = true, commandLineAPI = false, timeout } = {}) {
+  const { result, exceptionDetails } = await client.send(
+    'Runtime.evaluate',
+    { expression, awaitPromise, returnByValue: true, includeCommandLineAPI: commandLineAPI, userGesture: true },
+    { timeout },
+  );
+  if (exceptionDetails) {
+    const ex = exceptionDetails.exception;
+    // Un `throw 'texto'` o un rechazo con string no trae description, solo value.
+    const message = ex?.description || (ex && 'value' in ex ? String(ex.value) : exceptionDetails.text) || 'Evaluation failed';
+    throw Object.assign(new CdpError(message.split('\n')[0].replace(/^Error: /, '')), { status: 400, stack: message });
+  }
+  return result.type === 'undefined' ? undefined : result.value ?? result.description ?? null;
+}