@acertijosapps/electron-viewer 0.0.0-stage → 1.1.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,248 @@
-# 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, touch 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).
+- **Touch**: a touch mode in the viewer turns the pointer into a finger, and the agent can tap, swipe,
+  long press and pinch, for touch-first and kiosk apps.
+- **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 and open DevTools.
+- **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@1.1.0
+```
+
+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-vite, Electron Forge, a custom script), give the viewer
+your own start command. `{cdpPort}` and `{inspectPort}` are replaced with free debugging ports, and the
+Launch button (and `launch_app`) runs it in the project folder:
+
+```sh
+npx @acertijosapps/electron-viewer@1.1.0 --launch-cmd "yarn dev --remoteDebuggingPort {cdpPort} --inspect {inspectPort}"
+```
+
+That line is for electron-vite; for an npm script that ends in `electron .`, pass the flags after `--`:
+`--launch-cmd "npm start -- --remote-debugging-port={cdpPort} --inspect={inspectPort}"`. The command is
+only read from the command line or `ELECTRON_VIEWER_LAUNCH_CMD`, never from the HTTP API or the MCP.
+
+Or start the app yourself with the flags and the viewer finds it:
+
+```sh
+electron --remote-debugging-port=9222 --inspect=9229 .
+```
+
+Apps on CDP ports 9222–9231 are found automatically, and so is their main process when its inspector is
+on 9229–9238. `--inspect` is optional; without it you get everything except the main-process features
+(`evaluate_main`, real window resizing and in-app DevTools). To attach on other ports, use the form in
+the viewer or `--attach` and `--inspect`.
+
+```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)
+      --launch-cmd <cmd>   Launch with this shell command instead; {cdpPort} and {inspectPort}
+                           are replaced with the debugging ports
+  -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@1.1.0 mcp
+```
+
+Any other MCP client:
+
+```json
+{
+  "mcpServers": {
+    "electron-viewer": {
+      "command": "npx",
+      "args": ["-y", "@acertijosapps/electron-viewer@1.1.0", "mcp"]
+    }
+  }
+}
+```
+
+Also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.acertijosapps/electron-viewer`.
+
+The examples pin an exact version. The viewer and the MCP can run code in your app, so pin the version
+you reviewed instead of letting `npx` fetch whatever was published last, and update it on purpose.
+
+Keep the viewer running (`npx @acertijosapps/electron-viewer@1.1.0`) 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 |
+| `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 |
+| `tap` | One-finger tap (touch events, `pointerType: "touch"`) |
+| `swipe` | One-finger swipe: scrolls touch lists and drives swipe gestures |
+| `long_press` | Hold one finger down for a while, 800 ms by default |
+| `pinch` | Two-finger pinch around a point; `scale` > 1 zooms in, < 1 zooms out |
+| `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, an emulated viewport when the window can't reach the size (or with `emulate: true`) |
+| `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@1.1.0"],
+      "port": 8094,
+      "autoPort": false
+    }
+  ]
+}
+```
+
+## 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>` | 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/tap` | `{ x, y }` |
+| `POST /api/swipe` | `{ x1, y1, x2, y2, ms? }` |
+| `POST /api/long-press` | `{ x, y, ms? }` |
+| `POST /api/pinch` | `{ x?, y?, scale, ms? }` |
+| `POST /api/scroll` | `{ x, y, dx, dy }` |
+| `POST /api/text` | `{ text }` |
+| `POST /api/key` | `{ key, modifiers? }` |
+| `POST /api/resize` | `{ width, height, emulate? }` (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.
+- Touch goes through `Input.dispatchTouchEvent`. The first touch action on a window also turns on touch
+  emulation (`navigator.maxTouchPoints` 5, `pointer: coarse`) until the viewer or MCP that sent it exits.
+- Each process keeps one connection per window and per main process, which also collects console
+  messages and exceptions (the last 1000 per app).
+- For an app with no known inspector, each Node inspector on ports 9229–9238 is asked once, read only,
+  whether it is Electron and which CDP port its app listens on. Any other Node process started with
+  `--inspect` in that range gets one short connection (it logs `Debugger attached.`) and is left alone.
+- 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) isn't shown or
+  clickable; use `evaluate_main` to drive it from the main process. Capturing it would mean capturing the
+  screen, and with it any other window on top of the app, so the viewer doesn't.
+- Synchronous dialogs (`dialog.showMessageBoxSync`) block the main process: `evaluate_main` waits 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.
+- A long press reaches the app as a held touch, so apps that time `touchstart` themselves see it, but
+  Chromium on desktop doesn't turn it into a context menu. The viewer's touch mode is one finger; use
+  `pinch` for two.
+- No audio.
+- A `--launch-cmd` must pass the ports on to Electron; how depends on the tool. Launched apps keep running
+  when the viewer exits; close them from the app (or its terminal).
+
+## 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,112 @@
+#!/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)
+      --launch-cmd <cmd>   Launch with this shell command instead (env
+                           ELECTRON_VIEWER_LAUNCH_CMD); {cdpPort} and {inspectPort}
+                           are replaced with the debugging ports, e.g.
+                           "yarn dev --remoteDebuggingPort {cdpPort} --inspect {inspectPort}"
+
+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, 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 '--launch-cmd': {
+      const cmd = value();
+      if (!cmd.includes('{cdpPort}')) fail('--launch-cmd must include {cdpPort}');
+      process.env.ELECTRON_VIEWER_LAUNCH_CMD = cmd;
+      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;
+}