@restregular/dsh-visual-browser 0.1.0 → 0.1.1

package/lib/cdp.js

@@ -1,192 +1,208 @@
-/**
- * Minimal Chrome DevTools Protocol client.
- *
- * The plugin ships without dependencies: Node.js 22+ provides a WHATWG
- * `WebSocket`, which is all a flattened CDP session needs. Every command is a
- * JSON message with an `id`; flattened target sessions add `sessionId` to the
- * command and echo it on the matching response.
- */
-
-/** A CDP failure with a stable code so tools and routes can report a reason. */
-export class CdpError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.name = 'CdpError';
-    this.code = code;
-  }
-}
-
-const OPEN_TIMEOUT_MS = 15_000;
-const COMMAND_TIMEOUT_MS = 30_000;
-
-export class CdpConnection {
-  #socket;
-  #nextId = 1;
-  #pending = new Map();
-  #listeners = new Map();
-  #closed = false;
-
-  constructor(socket) {
-    this.#socket = socket;
-    socket.addEventListener('message', (event) => this.#onMessage(event.data));
-    socket.addEventListener('close', () => this.#failAll(new CdpError('CDP_CLOSED', 'the DevTools connection closed')));
-    socket.addEventListener('error', () => {
-      /* The close event carries the outcome; keep this listener quiet. */
-    });
-  }
-
-  /** Connect to a browser-level or page-level WebSocket endpoint. */
-  static async open(url, { timeoutMs = OPEN_TIMEOUT_MS } = {}) {
-    const Socket = globalThis.WebSocket;
-    if (typeof Socket !== 'function') {
-      throw new CdpError('CDP_UNAVAILABLE', 'this Node.js runtime has no built-in WebSocket (Node 22 or newer is required)');
-    }
-    const socket = new Socket(url);
-    await new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        cleanup();
-        try {
-          socket.close();
-        } catch {
-          /* already unusable */
-        }
-        reject(new CdpError('CDP_TIMEOUT', `timed out connecting to ${url}`));
-      }, timeoutMs);
-      const cleanup = () => {
-        clearTimeout(timer);
-        socket.removeEventListener('open', onOpen);
-        socket.removeEventListener('error', onError);
-      };
-      const onOpen = () => {
-        cleanup();
-        resolve();
-      };
-      const onError = () => {
-        cleanup();
-        reject(new CdpError('CDP_CONNECT_FAILED', `could not connect to ${url}`));
-      };
-      socket.addEventListener('open', onOpen);
-      socket.addEventListener('error', onError);
-    });
-    return new CdpConnection(socket);
-  }
-
-  get closed() {
-    return this.#closed;
-  }
-
-  /** Send one protocol command; `sessionId` targets a flattened session. */
-  send(method, params = {}, sessionId) {
-    if (this.#closed) return Promise.reject(new CdpError('CDP_CLOSED', 'the DevTools connection closed'));
-    const id = this.#nextId++;
-    const payload = { id, method, params };
-    if (sessionId !== undefined) payload.sessionId = sessionId;
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.#pending.delete(id);
-        reject(new CdpError('CDP_COMMAND_TIMEOUT', `${method} did not answer within ${COMMAND_TIMEOUT_MS}ms`));
-      }, COMMAND_TIMEOUT_MS);
-      this.#pending.set(id, { resolve, reject, method, timer });
-      try {
-        this.#socket.send(JSON.stringify(payload));
-      } catch (error) {
-        clearTimeout(timer);
-        this.#pending.delete(id);
-        reject(new CdpError('CDP_SEND_FAILED', messageOf(error)));
-      }
-    });
-  }
-
-  /** Subscribe to one protocol event; the returned function unsubscribes. */
-  on(method, listener) {
-    const bucket = this.#listeners.get(method) ?? new Set();
-    bucket.add(listener);
-    this.#listeners.set(method, bucket);
-    return () => {
-      bucket.delete(listener);
-      if (bucket.size === 0) this.#listeners.delete(method);
-    };
-  }
-
-  /** Resolve on the next `method` event, or reject on timeout. */
-  once(method, timeoutMs) {
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        off();
-        reject(new CdpError('CDP_EVENT_TIMEOUT', `waited ${timeoutMs}ms for ${method}`));
-      }, timeoutMs);
-      const off = this.on(method, (params, sessionId) => {
-        clearTimeout(timer);
-        off();
-        resolve({ params, sessionId });
-      });
-    });
-  }
-
-  close() {
-    if (this.#closed) return;
-    this.#failAll(new CdpError('CDP_CLOSED', 'the DevTools connection closed'));
-    try {
-      this.#socket.close();
-    } catch {
-      /* already closed */
-    }
-  }
-
-  #onMessage(raw) {
-    let message;
-    try {
-      message = JSON.parse(typeof raw === 'string' ? raw : String(raw));
-    } catch {
-      return;
-    }
-    if (message && typeof message.id === 'number') {
-      const pending = this.#pending.get(message.id);
-      if (pending === undefined) return;
-      this.#pending.delete(message.id);
-      clearTimeout(pending.timer);
-      if (message.error) {
-        pending.reject(
-          new CdpError(
-            `CDP_${String(message.error.code ?? 'ERROR')}`,
-            `${pending.method}: ${message.error.message ?? 'protocol error'}`,
-          ),
-        );
-      } else {
-        pending.resolve(message.result);
-      }
-      return;
-    }
-    if (!message || typeof message.method !== 'string') return;
-    const bucket = this.#listeners.get(message.method);
-    if (bucket === undefined) return;
-    for (const listener of [...bucket]) {
-      try {
-        listener(message.params, message.sessionId);
-      } catch {
-        /* a failing listener must not break the socket */
-      }
-    }
-  }
-
-  #failAll(error) {
-    if (this.#closed) return;
-    this.#closed = true;
-    for (const [id, pending] of this.#pending) {
-      clearTimeout(pending.timer);
-      this.#pending.delete(id);
-      pending.reject(error);
-    }
-    this.#listeners.clear();
-  }
-}
-
-export function messageOf(error) {
-  if (error instanceof Error) return error.message;
-  if (typeof error === 'string') return error;
-  try {
-    return JSON.stringify(error);
-  } catch {
-    return String(error);
-  }
-}
+/**
+ * Minimal Chrome DevTools Protocol client.
+ *
+ * The plugin ships without dependencies: Node.js 22+ provides a WHATWG
+ * `WebSocket`, which is all a flattened CDP session needs. Every command is a
+ * JSON message with an `id`; flattened target sessions add `sessionId` to the
+ * command and echo it on the matching response.
+ */
+
+/** A CDP failure with a stable code so tools and routes can report a reason. */
+export class CdpError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'CdpError';
+    this.code = code;
+  }
+}
+
+const OPEN_TIMEOUT_MS = 15_000;
+const COMMAND_TIMEOUT_MS = 30_000;
+
+export class CdpConnection {
+  #socket;
+  #nextId = 1;
+  #pending = new Map();
+  #listeners = new Map();
+  #closeListeners = new Set();
+  #closed = false;
+
+  constructor(socket) {
+    this.#socket = socket;
+    socket.addEventListener('message', (event) => this.#onMessage(event.data));
+    socket.addEventListener('close', () => this.#failAll(new CdpError('CDP_CLOSED', 'the DevTools connection closed')));
+    socket.addEventListener('error', () => {
+      /* The close event carries the outcome; keep this listener quiet. */
+    });
+  }
+
+  /** Connect to a browser-level or page-level WebSocket endpoint. */
+  static async open(url, { timeoutMs = OPEN_TIMEOUT_MS } = {}) {
+    const Socket = globalThis.WebSocket;
+    if (typeof Socket !== 'function') {
+      throw new CdpError('CDP_UNAVAILABLE', 'this Node.js runtime has no built-in WebSocket (Node 22 or newer is required)');
+    }
+    const socket = new Socket(url);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        try {
+          socket.close();
+        } catch {
+          /* already unusable */
+        }
+        reject(new CdpError('CDP_TIMEOUT', `timed out connecting to ${url}`));
+      }, timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.removeEventListener('open', onOpen);
+        socket.removeEventListener('error', onError);
+      };
+      const onOpen = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = () => {
+        cleanup();
+        reject(new CdpError('CDP_CONNECT_FAILED', `could not connect to ${url}`));
+      };
+      socket.addEventListener('open', onOpen);
+      socket.addEventListener('error', onError);
+    });
+    return new CdpConnection(socket);
+  }
+
+  get closed() {
+    return this.#closed;
+  }
+
+  /** Send one protocol command; `sessionId` targets a flattened session. */
+  send(method, params = {}, sessionId) {
+    if (this.#closed) return Promise.reject(new CdpError('CDP_CLOSED', 'the DevTools connection closed'));
+    const id = this.#nextId++;
+    const payload = { id, method, params };
+    if (sessionId !== undefined) payload.sessionId = sessionId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new CdpError('CDP_COMMAND_TIMEOUT', `${method} did not answer within ${COMMAND_TIMEOUT_MS}ms`));
+      }, COMMAND_TIMEOUT_MS);
+      this.#pending.set(id, { resolve, reject, method, timer });
+      try {
+        this.#socket.send(JSON.stringify(payload));
+      } catch (error) {
+        clearTimeout(timer);
+        this.#pending.delete(id);
+        reject(new CdpError('CDP_SEND_FAILED', messageOf(error)));
+      }
+    });
+  }
+
+  /** Subscribe to one protocol event; the returned function unsubscribes. */
+  on(method, listener) {
+    const bucket = this.#listeners.get(method) ?? new Set();
+    bucket.add(listener);
+    this.#listeners.set(method, bucket);
+    return () => {
+      bucket.delete(listener);
+      if (bucket.size === 0) this.#listeners.delete(method);
+    };
+  }
+
+  /** Resolve on the next `method` event, or reject on timeout. */
+  once(method, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new CdpError('CDP_EVENT_TIMEOUT', `waited ${timeoutMs}ms for ${method}`));
+      }, timeoutMs);
+      const off = this.on(method, (params, sessionId) => {
+        clearTimeout(timer);
+        off();
+        resolve({ params, sessionId });
+      });
+    });
+  }
+
+  /** Notified once with the failure that closed the socket. */
+  onClose(listener) {
+    this.#closeListeners.add(listener);
+    return () => this.#closeListeners.delete(listener);
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#failAll(new CdpError('CDP_CLOSED', 'the DevTools connection closed'));
+    try {
+      this.#socket.close();
+    } catch {
+      /* already closed */
+    }
+  }
+
+  #onMessage(raw) {
+    let message;
+    try {
+      message = JSON.parse(typeof raw === 'string' ? raw : String(raw));
+    } catch {
+      return;
+    }
+    if (message && typeof message.id === 'number') {
+      const pending = this.#pending.get(message.id);
+      if (pending === undefined) return;
+      this.#pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) {
+        pending.reject(
+          new CdpError(
+            `CDP_${String(message.error.code ?? 'ERROR')}`,
+            `${pending.method}: ${message.error.message ?? 'protocol error'}`,
+          ),
+        );
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+    if (!message || typeof message.method !== 'string') return;
+    const bucket = this.#listeners.get(message.method);
+    if (bucket === undefined) return;
+    for (const listener of [...bucket]) {
+      try {
+        listener(message.params, message.sessionId);
+      } catch {
+        /* a failing listener must not break the socket */
+      }
+    }
+  }
+
+  #failAll(error) {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const [id, pending] of this.#pending) {
+      clearTimeout(pending.timer);
+      this.#pending.delete(id);
+      pending.reject(error);
+    }
+    this.#listeners.clear();
+    const closeListeners = [...this.#closeListeners];
+    this.#closeListeners.clear();
+    for (const listener of closeListeners) {
+      try {
+        listener(error);
+      } catch {
+        /* a close listener must not block teardown */
+      }
+    }
+  }
+}
+
+export function messageOf(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@restregular/dsh-visual-browser",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Visual browser for DeepSeek Harness: the Agent drives a real Chrome through a token-light numbered view of interactive elements (never the raw DOM), while the Web UI streams the live page frame, the click point of every action, and a replayable operation timeline the user can also take over by clicking the picture.",
   "icon": "./icon.svg",
   "type": "module",
@@ -21,7 +21,8 @@
     "cordis.patch.yml",
     "icon.svg",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "test/"
   ],
   "dsh": {
     "bundle": {
@@ -66,6 +67,6 @@
   "license": "MIT",
   "author": "RestRegular",
   "scripts": {
-    "test": "node --check index.js && node --check client.js && node --check lib/browser.js && node test/snapshot.test.mjs && node test/scripts.test.mjs && node test/package.test.mjs"
+    "test": "node --check index.js && node --check client.js && node --check lib/browser.js && node test/format.test.mjs && node test/scripts.test.mjs && node test/routes.test.mjs && node test/package.test.mjs"
   }
 }

package/test/format.test.mjs

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict';
+import { formatSnapshot, describeAction, scrollProgress } from '../lib/format.js';
+
+const snapshot = {
+  url: 'https://demo.test/login',
+  title: '登录 - Demo',
+  viewport: { width: 1280, height: 800 },
+  scrollY: 400,
+  docHeight: 2400,
+  elements: [
+    { ref: 1, role: 'textbox', name: '手机号', value: '13800000000' },
+    { ref: 2, role: 'textbox', name: '密码', value: '••••••' },
+    { ref: 3, role: 'button', name: '登录', state: ['disabled'] },
+    { ref: 4, role: 'link', name: '忘记密码', href: '/forgot' },
+  ],
+  total: 6,
+  headings: ['用户登录', '没有账号?'],
+  text: '用户登录 手机号 密码 登录 忘记密码',
+  active: { ref: 2, role: 'textbox', name: '密码' },
+  frames: 1,
+};
+
+const text = formatSnapshot(snapshot, { maxElements: 100 });
+const lines = text.split('\n');
+assert.equal(lines[0], 'URL: https://demo.test/login');
+assert.equal(lines[1], 'TITLE: 登录 - Demo');
+assert.equal(lines[2], 'VIEW: 1280x800 scroll 400/2400 · 4/6 interactive');
+assert.ok(lines.includes('[1] textbox "手机号" value=13800000000'));
+assert.ok(lines.includes('[3] button "登录" (disabled)'));
+assert.ok(lines.includes('[4] link "忘记密码" → /forgot'));
+assert.ok(text.includes('ELEMENTS') === false, 'elements exist, so no placeholder line');
+assert.ok(text.includes('… 2 more interactive elements below the fold'), 'beyond-the-fold hint');
+assert.ok(text.includes('HEADINGS: 用户登录 | 没有账号?'));
+assert.ok(text.includes('TEXT: 用户登录 手机号 密码 登录 忘记密码'));
+assert.ok(text.includes('ACTIVE: [2] textbox "密码"'));
+assert.ok(text.includes('IFRAMES: 1'));
+
+// Empty page
+const empty = formatSnapshot({ url: 'about:blank', title: '', viewport: { width: 800, height: 600 }, elements: [], total: 0 });
+assert.ok(empty.includes('ELEMENTS: none visible in the viewport'));
+
+// maxElements clips and reports the remainder
+const clipped = formatSnapshot(snapshot, { maxElements: 2 });
+assert.equal(clipped.split('\n').filter((line) => line.startsWith('[')).length, 2);
+assert.ok(clipped.includes('… 4 more interactive elements'));
+
+// Guard against junk input
+assert.equal(formatSnapshot(null), 'No page snapshot available.');
+assert.ok(formatSnapshot({}).startsWith('URL: about:blank'));
+assert.ok(formatSnapshot({ url: 'x' }).startsWith('URL: x'));
+
+// Action descriptions for the timeline
+assert.equal(describeAction({ kind: 'click', target: '[3]', detail: 'click [3] “登录”' }), 'click [3] “登录”');
+assert.equal(describeAction({ kind: 'click', target: '[3]' }), 'click [3]');
+assert.equal(describeAction('hello'), 'hello');
+assert.equal(describeAction(null), '');
+
+// Scroll progress
+assert.equal(scrollProgress(snapshot), Math.round((400 / (2400 - 800)) * 100));
+assert.equal(scrollProgress({ scrollY: 0, docHeight: 700, viewport: { height: 800 } }), 0);
+
+console.log('format.test.mjs ok');

package/test/package.test.mjs

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const readJson = async (name) => JSON.parse(await readFile(join(root, name), 'utf8'));
+
+const pkg = await readJson('package.json');
+assert.equal(pkg.name, '@restregular/dsh-visual-browser');
+assert.match(pkg.version, /^\d+\.\d+\.\d+$/);
+assert.equal(pkg.type, 'module');
+assert.ok(pkg.description.length > 80, 'description explains the capability');
+assert.equal(pkg.icon, './icon.svg');
+assert.equal(pkg.dsh.bundle.patch, './cordis.patch.yml');
+assert.equal(pkg.dsh.client.platform, 'web');
+assert.ok(Array.isArray(pkg.dsh.client.inject) && pkg.dsh.client.inject.length > 0);
+assert.deepEqual(pkg.exports['./client'], './client.js');
+assert.ok(pkg.files.includes('client.js'));
+assert.ok(pkg.files.includes('index.js'));
+assert.ok(pkg.files.includes('lib/'));
+assert.ok(pkg.files.includes('cordis.patch.yml'));
+assert.ok(pkg.files.includes('icon.svg'));
+assert.ok(pkg.files.includes('locale/*.json'));
+
+const patch = await readFile(join(root, 'cordis.patch.yml'), 'utf8');
+assert.ok(patch.includes(`name: '${pkg.name}'`), 'patch row name must equal the package name');
+assert.ok(patch.includes('- insert:'));
+assert.ok(patch.includes('id: dsh-visual-browser'));
+
+for (const locale of ['en', 'zh']) {
+  const dict = await readJson(`locale/${locale}.json`);
+  assert.ok(dict.meta && dict.meta.title, `${locale} meta title`);
+  assert.ok(dict.meta.description && dict.meta.description.length > 40, `${locale} meta description`);
+}
+assert.notEqual((await readJson('locale/en.json')).meta.title, (await readJson('locale/zh.json')).meta.title);
+
+const icon = await readFile(join(root, 'icon.svg'), 'utf8');
+assert.ok(icon.startsWith('<svg'), 'icon is an SVG');
+assert.ok(icon.includes('viewBox="0 0 256 256"'));
+assert.ok(icon.includes('</svg>'));
+
+// The Host half must be importable and expose the Loader surface.
+const host = await import(pathToFileURL(join(root, 'index.js')).href);
+assert.equal(host.name, 'dsh-visual-browser');
+assert.equal(typeof host.apply, 'function');
+
+// The client bundle is not a module: it registers through the module loader.
+const client = await readFile(join(root, 'client.js'), 'utf8');
+assert.ok(client.includes('__ModuleLoader__.load'), 'client registers with the module loader');
+assert.ok(client.includes(`id: MODULE_ID`));
+assert.ok(client.includes(`'sidebar.panellist'`), 'sidebar entry');
+assert.ok(client.includes(`'main'`), 'main panel');
+assert.ok(!/(^|\n)\s*(const|let)\s+[A-Za-z_$][\w$]*\s*=/.test(client.replace(/^\s*\/\/.*$/gm, '')) || client.trimStart().startsWith('(function'), 'client file is wrapped in an IIFE');
+
+console.log('package.test.mjs ok');