juce-webview-agent-bridge 0.3.0

package/tools/shared.d.mts

@@ -0,0 +1,21 @@
+import type { Socket } from 'node:net';
+export interface Discovery {
+    port?: number;
+    token?: string;
+    [key: string]: unknown;
+}
+/** The port the host tries first (it scans upward on collision); clients fall
+ *  back to it when no discovery file exists. Mirrors WebAgentBridge::start(). */
+export declare const DEFAULT_PORT = 8930;
+/** Locate a running bridge's {port, token}.
+ *  The host writes them on start so clients never guess: each instance registers
+ *  <home>/.web_agent_bridge.d/<port>.json (so several hosts — e.g. multiple
+ *  plugin instances in a DAW — don't clobber each other), plus the single legacy
+ *  <home>/.web_agent_bridge.json for older single-instance hosts. Enumerate the
+ *  registry and pick the requested port (or the lowest), then fall back to the
+ *  legacy file. Returns {} when nothing is found. */
+export declare function loadDiscovery(preferredPort?: number): Discovery;
+/** Attach an NDJSON reader to a socket: reassembles newline-delimited JSON
+ *  lines across TCP chunks (multi-byte-safe via StringDecoder) and calls fn
+ *  with each parsed message. Unparseable or blank lines are skipped. */
+export declare function onJsonLines(sock: Pick<Socket, 'on'>, fn: (message: Record<string, unknown>) => void): void;

package/tools/shared.mjs

@@ -0,0 +1,76 @@
+/*
+ * shared.mjs — the facts both clients (web-agent.mjs, e2e.mjs) must agree on:
+ * bridge discovery and NDJSON wire framing. Single source of truth — the two
+ * clients used to carry private copies of this logic, and the copies drifted
+ * (the fill focus fix landed in one and not the other), so it now lives here.
+ * Still zero third-party dependencies: bare Node >= 18 built-ins only.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+/** The port the host tries first (it scans upward on collision); clients fall
+ *  back to it when no discovery file exists. Mirrors WebAgentBridge::start(). */
+export const DEFAULT_PORT = 8930;
+/** Locate a running bridge's {port, token}.
+ *  The host writes them on start so clients never guess: each instance registers
+ *  <home>/.web_agent_bridge.d/<port>.json (so several hosts — e.g. multiple
+ *  plugin instances in a DAW — don't clobber each other), plus the single legacy
+ *  <home>/.web_agent_bridge.json for older single-instance hosts. Enumerate the
+ *  registry and pick the requested port (or the lowest), then fall back to the
+ *  legacy file. Returns {} when nothing is found. */
+export function loadDiscovery(preferredPort) {
+    const home = os.homedir();
+    const dir = path.join(home, '.web_agent_bridge.d');
+    const readJson = (p) => { try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    } };
+    if (preferredPort) {
+        const d = readJson(path.join(dir, `${preferredPort}.json`));
+        if (d)
+            return d;
+    }
+    try {
+        const insts = fs.readdirSync(dir).filter((f) => f.endsWith('.json'))
+            .map((f) => readJson(path.join(dir, f)))
+            .filter((d) => d !== null && typeof d.port === 'number')
+            .sort((a, b) => a.port - b.port);
+        if (preferredPort) {
+            const m = insts.find((d) => d.port === preferredPort);
+            if (m)
+                return m;
+        }
+        if (insts.length)
+            return insts[0];
+    }
+    catch { /* no dir -> fall through to legacy */ }
+    return readJson(path.join(home, '.web_agent_bridge.json')) || {};
+}
+/** Attach an NDJSON reader to a socket: reassembles newline-delimited JSON
+ *  lines across TCP chunks (multi-byte-safe via StringDecoder) and calls fn
+ *  with each parsed message. Unparseable or blank lines are skipped. */
+export function onJsonLines(sock, fn) {
+    let acc = '';
+    const dec = new StringDecoder('utf8');
+    sock.on('data', (d) => {
+        acc += dec.write(d);
+        let nl;
+        while ((nl = acc.indexOf('\n')) >= 0) {
+            const line = acc.slice(0, nl);
+            acc = acc.slice(nl + 1);
+            if (!line.trim())
+                continue;
+            let m;
+            try {
+                m = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            fn(m);
+        }
+    });
+}

package/tools/web-agent.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/tools/web-agent.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/*
+ * CLI client for juce_webview_agent_bridge.
+ *
+ * Talks the newline-delimited JSON protocol to a plugin/app that embeds the
+ * web_agent_bridge module, so an external agent gets a browser-like toolkit on
+ * the live WebView: eval, console/network stream, DOM, click/fill, screenshot.
+ *
+ * Usage:
+ *   juce-webview-agent-bridge eval "<js>"            run JS, print result/error
+ *   juce-webview-agent-bridge dom [selector]         outerHTML of selector (or <html>)
+ *   juce-webview-agent-bridge click <selector>       element.click()  (isTrusted=false)
+ *   juce-webview-agent-bridge fill <selector> <val>  React-safe value set + input event
+ *   juce-webview-agent-bridge capture <on|off>       toggle response-body capture
+ *   juce-webview-agent-bridge backlog                dump the page ring buffer
+ *   juce-webview-agent-bridge logs [--backlog]       stream console/network (Ctrl-C to stop); --backlog dumps recent history first
+ *   juce-webview-agent-bridge shot [out.png] [sel]   native screenshot (macOS/Windows); with a selector, crop to that element
+ *   juce-webview-agent-bridge layerdebug [on|off]    WebKit compositing overlays: layer borders + repaint counters (macOS)
+ *   juce-webview-agent-bridge layertree              dump the remote CALayer tree as text (macOS, programmatic layer census)
+ *   juce-webview-agent-bridge ping                   liveness check
+ *   juce-webview-agent-bridge hello                  capabilities handshake (version, platform, ops, screenshotAvailable)
+ *
+ * Options:  --port <n>   (default $WEB_AGENT_PORT or 8930)
+ *           --host <h>   (default 127.0.0.1)
+ */
+import net from 'node:net';
+import path from 'node:path';
+import { DEFAULT_PORT, loadDiscovery, onJsonLines } from './shared.mjs';
+const argv = process.argv.slice(2);
+const opt = (name, def) => {
+    const i = argv.indexOf(name);
+    if (i >= 0 && i + 1 < argv.length) {
+        const v = argv[i + 1];
+        argv.splice(i, 2);
+        return v;
+    }
+    return def;
+};
+const HOST = opt('--host', '127.0.0.1');
+const portArg = opt('--port', process.env.WEB_AGENT_PORT || '');
+const tokenArg = opt('--token', process.env.WEB_AGENT_TOKEN || '');
+const disc = loadDiscovery(portArg ? Number(portArg) : undefined);
+const PORT = Number(portArg || disc.port || DEFAULT_PORT);
+const TOKEN = tokenArg || disc.token || '';
+const [cmd, ...rest] = argv;
+function connect() {
+    return new Promise((resolve, reject) => {
+        const sock = net.connect({ host: HOST, port: PORT }, () => resolve(sock));
+        sock.on('error', reject);
+    });
+}
+// Send one request line, resolve with the first matching reply (by id).
+function request(obj, { timeoutMs = 15000 } = {}) {
+    return new Promise(async (resolve, reject) => {
+        let sock;
+        try {
+            sock = await connect();
+        }
+        catch (e) {
+            return reject(e);
+        }
+        const id = Math.floor(Math.random() * 1e9);
+        const timer = setTimeout(() => { sock.destroy(); reject(new Error('timeout')); }, timeoutMs);
+        onJsonLines(sock, (m) => {
+            if (m.id === id) {
+                clearTimeout(timer);
+                sock.end();
+                resolve(m);
+            }
+        });
+        sock.on('error', (e) => { clearTimeout(timer); reject(e); });
+        sock.write(JSON.stringify({ ...obj, id, ...(TOKEN ? { token: TOKEN } : {}) }) + '\n');
+    });
+}
+async function evalJs(code, timeoutMs = 15000) {
+    const r = await request({ op: 'eval', code }, { timeoutMs });
+    if (!r.ok)
+        throw new Error(r.error || 'eval failed');
+    return r.result;
+}
+function fmt(v) {
+    if (typeof v === 'string')
+        return v;
+    try {
+        return JSON.stringify(v, null, 2);
+    }
+    catch {
+        return String(v);
+    }
+}
+// React-19-safe value setter + input/change dispatch. Focus BEFORE mutating the
+// value, like a real edit — some controlled inputs gate their commit on
+// focus->change->blur ordering and silently drop a value set without focus
+// (same rationale as fillCode in e2e.mjs; keep the two in behavioural lockstep).
+const fillSnippet = (sel, val) => `(() => {
+  const el = document.querySelector(${JSON.stringify(sel)});
+  if (!el) return 'no element: ' + ${JSON.stringify(sel)};
+  if (!(el instanceof window.HTMLInputElement || el instanceof window.HTMLTextAreaElement)) return 'not an input/textarea: ' + el.tagName;
+  if (typeof el.focus === 'function') el.focus();
+  const proto = el instanceof window.HTMLTextAreaElement ? window.HTMLTextAreaElement.prototype : window.HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, 'value').set;
+  setter.call(el, ${JSON.stringify(val)});
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+  el.dispatchEvent(new Event('change', { bubbles: true }));
+  return 'ok';
+})()`;
+async function main() {
+    switch (cmd) {
+        case 'ping': {
+            const r = await request({ op: 'ping' });
+            console.log(r.ok ? `pong (127.0.0.1:${PORT})` : 'no pong');
+            break;
+        }
+        case 'layerdebug': {
+            const enabled = rest[0] !== 'off';
+            const r = await request({ op: 'layerdebug', enabled });
+            console.log(r.ok
+                ? `compositing overlays ${enabled ? 'ON' : 'OFF'} (layer borders + repaint counters)`
+                : `failed: ${r.error || 'unavailable'}`);
+            break;
+        }
+        case 'layertree': {
+            const r = await request({ op: 'layertree' });
+            console.log(r.ok ? r.text : `failed: ${r.error || 'unavailable'}`);
+            break;
+        }
+        case 'hello': {
+            const r = await request({ op: 'hello' });
+            console.log(fmt({
+                protocolVersion: r.protocolVersion, platform: r.platform,
+                screenshotAvailable: r.screenshotAvailable, authRequired: r.authRequired, ops: r.ops,
+            }));
+            break;
+        }
+        case 'eval': {
+            if (!rest[0])
+                throw new Error('usage: eval "<js>"');
+            console.log(fmt(await evalJs(rest.join(' '))));
+            break;
+        }
+        case 'dom': {
+            const sel = rest[0] || 'html';
+            const code = `(() => { const el = document.querySelector(${JSON.stringify(sel)}); return el ? el.outerHTML : 'no element: ' + ${JSON.stringify(sel)}; })()`;
+            console.log(fmt(await evalJs(code)));
+            break;
+        }
+        case 'click': {
+            if (!rest[0])
+                throw new Error('usage: click <selector>');
+            const sel = rest.join(' ');
+            const code = `(() => { const el = document.querySelector(${JSON.stringify(sel)}); if (!el) return 'no element'; el.scrollIntoView(); el.click(); return 'clicked'; })()`;
+            console.log(fmt(await evalJs(code)));
+            break;
+        }
+        case 'fill': {
+            if (rest.length < 2)
+                throw new Error('usage: fill <selector> <value>');
+            const sel = rest[0];
+            const val = rest.slice(1).join(' ');
+            console.log(fmt(await evalJs(fillSnippet(sel, val))));
+            break;
+        }
+        case 'capture': {
+            const on = (rest[0] || 'on') === 'on';
+            await evalJs(`(window.__webAgentCapture = ${on}, '${on ? 'on' : 'off'}')`);
+            console.log(`response-body capture: ${on ? 'on' : 'off'}`);
+            break;
+        }
+        case 'backlog': {
+            const r = await evalJs(`JSON.stringify(window.__webAgentBuffer || [])`);
+            const arr = typeof r === 'string' ? JSON.parse(r) : r;
+            for (const e of arr)
+                printSink(e);
+            break;
+        }
+        case 'shot': {
+            // Native capture inside the plugin (ScreenCaptureKit/WGC) — includes WebGL,
+            // no external CLI. Optional path: where the plugin writes the PNG. Optional
+            // selector: crop to that element's rect (a much smaller PNG / fewer tokens).
+            // Resolve to an absolute path against the CLIENT's CWD: the plugin runs
+            // with a different CWD (its .app bundle), so a relative path would both
+            // trip JUCE's File-ctor assertion (juce_File.cpp:219 wants absolute) and
+            // write the PNG next to the bundle instead of where the caller expects.
+            const out = rest[0] ? path.resolve(rest[0]) : undefined;
+            const sel = rest[1];
+            let rect;
+            if (sel) {
+                const box = await evalJs(`(() => { const el = document.querySelector(${JSON.stringify(sel)}); if (!el) return null; const r = el.getBoundingClientRect(); return { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) }; })()`);
+                if (!box)
+                    throw new Error('no element: ' + sel);
+                rect = box;
+            }
+            const r = await request({ op: 'shot', ...(out ? { path: out } : {}), ...(rect ? { rect } : {}) }, { timeoutMs: 30000 });
+            if (!r.ok)
+                throw new Error(r.error || 'native screenshot failed');
+            console.log(r.path);
+            break;
+        }
+        case 'logs': {
+            // A freshly-connected client only sees events from now on; --backlog first
+            // dumps the page ring buffer so you also get the recent history in one go.
+            if (rest.includes('--backlog') || rest.includes('-b')) {
+                try {
+                    const buf = await evalJs(`JSON.stringify(window.__webAgentBuffer || [])`);
+                    for (const e of (typeof buf === 'string' ? JSON.parse(buf) : buf))
+                        printSink(e);
+                }
+                catch (e) {
+                    process.stderr.write(`[juce-webview-agent-bridge] backlog unavailable: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
+            }
+            const sock = await connect();
+            if (TOKEN)
+                sock.write(JSON.stringify({ op: 'auth', token: TOKEN }) + '\n'); // authenticate before streaming
+            process.stderr.write(`[juce-webview-agent-bridge] streaming from 127.0.0.1:${PORT} (Ctrl-C to stop)\n`);
+            onJsonLines(sock, (m) => { if (m.op === 'sink')
+                printSink(m.event); });
+            sock.on('error', (e) => { console.error(e.message); process.exit(1); });
+            sock.on('close', () => process.exit(0));
+            break;
+        }
+        default:
+            console.error('unknown command. run with no valid command to see usage in the header.');
+            process.exit(2);
+    }
+}
+function printSink(e) {
+    if (!e)
+        return;
+    const ts = new Date(e.t || Date.now()).toISOString().slice(11, 23);
+    const d = e.data || {};
+    if (e.kind === 'console')
+        console.log(`${ts} ${(d.level || 'log').toUpperCase().padEnd(5)} ${(d.args || []).join(' ')}`);
+    else if (e.kind === 'error')
+        console.log(`${ts} ERROR ${d.message || ''}${d.stack ? '\n' + d.stack : ''}`);
+    else if (e.kind === 'net') {
+        // data.kind: fetch | xhr | ws | sse | beacon | timing. ws/sse carry event(+dir);
+        // request/response bodies + headers ride along only while `capture` is armed.
+        const tag = (d.kind || 'net').toUpperCase().padEnd(6);
+        const ev = d.event ? d.event + (d.dir ? '/' + d.dir : '') : (d.method || '');
+        const req = d.reqBody ? '\n  req:  ' + d.reqBody : '';
+        const body = d.body ? '\n  body: ' + d.body : '';
+        console.log(`${ts} ${tag}${ev} ${d.status ?? d.code ?? ''} ${d.url || d.name || ''} ${d.ms != null ? d.ms + 'ms' : ''}${req}${body}`);
+    }
+    else
+        console.log(`${ts} ${e.kind} ${fmt(d)}`);
+}
+main()
+    .then(() => { if (cmd !== 'logs')
+    process.exit(0); })
+    .catch((e) => { console.error('error:', e instanceof Error ? e.message : String(e)); process.exit(1); });