juce-webview-agent-bridge 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+Notable user-facing changes are recorded here. Release artifacts and complete
+commit comparisons are available from the linked GitHub Releases.
+
+## [Unreleased]
+
+### Added
+
+- The `hello` reply now reports `moduleVersion`, the version of the C++ module
+  the host embeds. `protocolVersion` only moves on a breaking change, so it
+  could not identify a plugin built against an older module pin.
+- Both clients now negotiate capabilities against the `hello` handshake. An API
+  that needs an op the host does not provide fails immediately with an error
+  naming the host module version, the client version, and the fix (bump the
+  plugin's `GIT_TAG` and rebuild) instead of the host's bare `unknown op`.
+  Connecting to a host that advertises a newer protocol major now fails outright
+  rather than misbehaving later.
+
+### Fixed
+
+- `page.replayEvents()` now surfaces a failed `sink_replay` reply as an error
+  instead of silently resolving with an undefined count.
+- `connect()` now fails when the host rejects the page-helper injection, instead
+  of returning a session whose every locator then failed for unclear reasons.
+  A failed authentication also surfaces here rather than passing silently.
+- `connect()` no longer leaves the connection open when initialization fails.
+
+### Changed
+
+- The CLI performs the handshake once per run, so a host advertising a newer
+  protocol major is refused before the command runs rather than part-way through.
+  `ping` and `hello` are exempt: they are the diagnostics you need in order to
+  see a version mismatch at all.
+- `page.capabilities()` returns the handshake taken during `connect()` (it
+  cannot change within a connection) instead of issuing a second `hello`.
+  `page.caps` exposes the same value, or `null` against a host too old to answer
+  the handshake — in which case every capability guard stands down, so existing
+  setups keep working unchanged.
+
+## [0.4.0] - 2026-07-18
+
+### Added
+
+- Added a maintained project changelog and repository social preview.
+
+### Changed
+
+- Improved the npm package description and search keywords.
+- Raised the supported Node.js floor from the end-of-life Node 18 to Node 22;
+  CI now covers the supported Node 22 and 24 LTS lines.
+- Added npm version and license badges to the README.
+
+## [0.3.1] - 2026-07-18
+
+### Changed
+
+- Replaced long-lived npm publishing tokens with Trusted Publishing through
+  GitHub Actions OIDC.
+- Updated the official GitHub Actions to their Node 24-compatible releases.
+
+There are no package API changes in this release.
+
+## [0.3.0] - 2026-07-18
+
+### Added
+
+- Published the zero-runtime-dependency Node client as
+  `juce-webview-agent-bridge`.
+- Added strict TypeScript sources and declarations for the Playwright-shaped E2E
+  API, shared discovery helpers, and CLI.
+- Added package smoke tests covering clean installation, imports, declarations,
+  and the canonical `npx juce-webview-agent-bridge` command.
+- Added the root CMake entry point for JUCE consumers using `FetchContent`.
+- Added the manually triggered, fully tested GitHub and npm release workflow.
+
+## [0.2.2] - 2026-07-17
+
+### Fixed
+
+- Kept the native Windows screenshot backend compatible with the documented
+  C++17 minimum when recent MSVC libraries include C++/WinRT coroutine headers.
+
+## [0.2.1] - 2026-07-17
+
+### Added
+
+- Added native Windows 11 screenshots using Windows Graphics Capture and D3D11.
+- Added full-window and selector-based captures with DPI-aware cropping.
+- Advertised Windows screenshot support through the `hello` handshake.
+
+## [0.2.0] - 2026-07-16
+
+### Added
+
+- Added the macOS `layerdebug` op and `page.layerDebug()` for WebKit compositing
+  overlays.
+- Added the macOS `layertree` op and `page.layerTree()` for programmatic CALayer
+  inspection.
+- Added `parseLayerTree()` for extracting layer geometry from tree dumps.
+
+### Changed
+
+- Expanded CI to require the C++ suite on Windows and Linux.
+- Split detailed E2E and protocol documentation out of the README.
+
+## [0.1.0] - 2026-07-13
+
+### Added
+
+- Initial debug-only JUCE WebView bridge with loopback discovery and session
+  authentication.
+- JavaScript evaluation, DOM interaction, console/error/network capture, event
+  replay, and native macOS screenshots.
+- Zero-dependency CLI, Playwright-shaped E2E client, agent skill, and standalone
+  JavaScript and C++ test suites.
+
+[Unreleased]: https://github.com/mateusz28011/juce-webview-agent-bridge/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/mateusz28011/juce-webview-agent-bridge/releases/tag/v0.4.0
+[0.3.1]: https://github.com/mateusz28011/juce-webview-agent-bridge/releases/tag/v0.3.1
+[0.3.0]: https://github.com/mateusz28011/juce-webview-agent-bridge/releases/tag/v0.3.0
+[0.2.2]: https://github.com/mateusz28011/juce-webview-agent-bridge/releases/tag/v0.2.2
+[0.2.1]: https://github.com/mateusz28011/juce-webview-agent-bridge/releases/tag/v0.2.1
+[0.2.0]: https://github.com/mateusz28011/juce-webview-agent-bridge/releases/tag/v0.2.0
+[0.1.0]: https://github.com/mateusz28011/juce-webview-agent-bridge/releases/tag/v0.1.0

package/README.md

@@ -1,6 +1,10 @@
-# juce_webview_agent_bridge
+# JUCE WebView Agent Bridge
 
+[![npm version](https://img.shields.io/npm/v/juce-webview-agent-bridge.svg)](https://www.npmjs.com/package/juce-webview-agent-bridge)
 [![tests](https://github.com/mateusz28011/juce-webview-agent-bridge/actions/workflows/tests.yml/badge.svg)](https://github.com/mateusz28011/juce-webview-agent-bridge/actions/workflows/tests.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+![JUCE WebView plugin connected to an agent and E2E tests](https://raw.githubusercontent.com/mateusz28011/juce-webview-agent-bridge/main/docs/social-preview.png)
 
 A **debug-only** JUCE module that lets an external agent (or script) drive a live
 `juce::WebBrowserComponent` over a loopback TCP socket — a "mini-CDP" giving you a
@@ -70,7 +74,7 @@ inspection remains macOS-only. Linux real-app reports and fixes are very welcome
 ## Install
 
 **Requirements:** JUCE 8, C++17, a `juce::WebBrowserComponent`-based UI; the
-clients need Node ≥ 18 (zero runtime dependencies).
+clients need Node ≥ 22 (zero runtime dependencies).
 
 It's a standard JUCE module. Get the repo — as a submodule:
 
@@ -85,7 +89,7 @@ or with CMake `FetchContent` (after JUCE has been added, so
 include(FetchContent)
 FetchContent_Declare(juce_webview_agent_bridge
     GIT_REPOSITORY https://github.com/mateusz28011/juce-webview-agent-bridge.git
-    GIT_TAG        v0.3.1)
+    GIT_TAG        v0.5.0)
 FetchContent_MakeAvailable(juce_webview_agent_bridge)
 ```
 
@@ -201,7 +205,7 @@ Both suites live in `tests/` and run **independently of any host app**, so they
 keep working after this module is extracted into its own repo.
 
 ```bash
-# JS client — zero dependencies, Node >= 18
+# JS client — zero dependencies, Node >= 22
 npm test                     # or: node --test tests/*.test.mjs
 
 # Maintainer build — strict TypeScript source -> committed .mjs + .d.mts

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "juce-webview-agent-bridge",
-  "version": "0.3.1",
-  "description": "CLI + protocol client for the juce_webview_agent_bridge debug WebView bridge (eval/console/network/click/fill/screenshot over a loopback socket, no CDP).",
+  "version": "0.5.0",
+  "description": "Typed, zero-dependency E2E client and CLI for driving live JUCE WebViews over a debug-only loopback bridge, without CDP.",
+  "keywords": [
+    "juce",
+    "webview",
+    "wkwebview",
+    "webview2",
+    "e2e",
+    "testing",
+    "playwright",
+    "agent",
+    "automation",
+    "debugging",
+    "mcp-alternative"
+  ],
   "type": "module",
   "types": "./tools/e2e.d.mts",
   "exports": {
@@ -31,6 +44,7 @@
   "files": [
     "tools/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "license": "MIT",
@@ -39,7 +53,7 @@
     "url": "git+https://github.com/mateusz28011/juce-webview-agent-bridge.git"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"

package/tools/e2e.d.mts

@@ -1,4 +1,5 @@
 import type { Socket } from 'node:net';
+import type { BridgeCapabilities } from './shared.mjs';
 type ProtocolMessage = Record<string, any>;
 type LogFn = (message: string) => void;
 type TimeoutOptions = {
@@ -43,13 +44,10 @@ export type NetworkEventData = {
     status?: number;
     [key: string]: unknown;
 };
-export type Capabilities = {
-    protocolVersion: number;
-    platform: string;
-    ops: string[];
-    screenshotAvailable: boolean;
-    authRequired: boolean;
-};
+/** The `hello` handshake. Shape owned by shared.mts (both clients negotiate
+    against it); re-exported here under the name this client has always used. */
+export type Capabilities = BridgeCapabilities;
+export type { BridgeCapabilities };
 export type RenderPerfResult = {
     durMs: number;
     commitsPerSec: number;
@@ -162,12 +160,16 @@ export declare class Page {
     readonly interval: number;
     readonly backendTimeoutMs: number;
     readonly log: LogFn;
+    /** The `hello` handshake taken at connect(), or null when the host could not
+        answer it. Immutable for the life of the connection (one host process). */
+    readonly caps: BridgeCapabilities | null;
     logFile: string | null;
-    constructor(session: Session, { defaultTimeout, interval, log, backendTimeoutMs }: {
+    constructor(session: Session, { defaultTimeout, interval, log, backendTimeoutMs, caps }: {
         defaultTimeout: number;
         interval: number;
         log: LogFn;
         backendTimeoutMs?: number;
+        caps?: BridgeCapabilities | null;
     });
     locator(selector: string): Locator;
     getByTestId(id: string): Locator;
@@ -241,8 +243,10 @@ export declare class Page {
         motionSelector?: string | null;
     }): Promise<RenderPerfResult>;
     /** Capabilities handshake: { protocolVersion, platform, ops, screenshotAvailable,
-        authRequired }. Lets a caller branch on what the host supports (e.g. skip
-        screenshots when screenshotAvailable is false) without probing op-by-op. */
+        authRequired, moduleVersion? }. Lets a caller branch on what the host supports
+        (e.g. skip screenshots when screenshotAvailable is false) without probing
+        op-by-op. Returns the handshake connect() already took — it cannot change
+        within a connection — and only asks again if that one did not land. */
     capabilities(): Promise<Capabilities>;
     /** Toggle WebKit's compositing debug overlays (layer borders + repaint
         counters) on the host's WKWebView via the bridge `layerdebug` op. The
@@ -356,4 +360,3 @@ export interface ExpectFunction {
     poll<T>(fn: () => T | Promise<T>, options?: PollExpectOptions): PollAssertions<T>;
 }
 export declare const expect: ExpectFunction;
-export {};

package/tools/e2e.mjs

@@ -31,7 +31,7 @@ import net from 'node:net';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { DEFAULT_PORT, loadDiscovery, onJsonLines } from './shared.mjs';
+import { DEFAULT_PORT, assertProtocolSupported, loadDiscovery, onJsonLines, parseHello, requireOp } from './shared.mjs';
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Bring the host app's window to the foreground (macOS, best-effort; resolves
  *  false elsewhere). A backgrounded WebView reports document.hidden === true and
@@ -450,6 +450,21 @@ class Session {
     }
     catch { } }
 }
+/** Run the `hello` handshake and validate the protocol major.
+    Null means "capabilities unknown" — a host too old to answer `hello` must
+    stay usable exactly as before, so every guard stands down.
+
+    A transport failure is NOT folded into null: the reference host always
+    answers unknown ops with `ok:false`, so an exception here means the
+    connection is broken, and swallowing it would silently disable the guards
+    for the rest of the session. Validating here (rather than at the call site)
+    keeps the retry in capabilities() from returning an unvalidated host. */
+async function handshake(session) {
+    const caps = parseHello(await session.request({ op: 'hello' }));
+    if (caps)
+        assertProtocolSupported(caps);
+    return caps;
+}
 // ---- public API -----------------------------------------------------------
 export async function connect({ host = '127.0.0.1', port, token, timeout = 5000, interval = 50, log, logFile, logEcho, backendTimeoutMs = 10000, activate } = {}) {
     // Foreground the host window first (see activateApp) so polling/timers are live
@@ -472,10 +487,29 @@ export async function connect({ host = '127.0.0.1', port, token, timeout = 5000,
     });
     sock.unref(); // the persistent client socket must not, by itself, keep node alive
     const session = new Session(sock, resolvedToken);
-    if (resolvedToken)
-        await session.request({ op: 'auth', token: resolvedToken });
-    await session.request({ op: 'eval', code: PAGE_HELPERS }); // inject helpers once
-    const page = new Page(session, { defaultTimeout: timeout, interval, log: logger, backendTimeoutMs });
+    // Every failure past this point must close the socket before rethrowing:
+    // unref() keeps the client socket from holding Node open on its own, but an
+    // abandoned connection still pins the host's server handle.
+    let caps;
+    try {
+        if (resolvedToken)
+            await session.request({ op: 'auth', token: resolvedToken });
+        // Negotiate up front (one loopback round-trip): the client and the host's C++
+        // module version independently, so this is what turns a stale module pin into
+        // a named mismatch instead of a late `unknown op` or an unchecked reply.
+        caps = await handshake(session);
+        requireOp(caps, 'eval', 'connect()'); // the helpers below, and every locator, ride on it
+        const injected = await session.request({ op: 'eval', code: PAGE_HELPERS }); // inject helpers once
+        // An unchecked injection hands back a Page whose every locator then fails
+        // cryptically; a failed auth also surfaces here rather than silently.
+        if (!injected.ok)
+            throw new Error(`bridge rejected the page helpers: ${injected.error || 'unknown error'}`);
+    }
+    catch (e) {
+        session.close();
+        throw e;
+    }
+    const page = new Page(session, { defaultTimeout: timeout, interval, log: logger, backendTimeoutMs, caps });
     page.logFile = file; // where actions are being written (null if a custom log fn was passed)
     return page;
 }
@@ -485,14 +519,18 @@ export class Page {
     interval;
     backendTimeoutMs;
     log;
+    /** The `hello` handshake taken at connect(), or null when the host could not
+        answer it. Immutable for the life of the connection (one host process). */
+    caps;
     logFile = null;
     // opts.log?: (msg) => void — when given, every action (click/fill/drag/backend/
     // fire) emits a concise progress line as it runs. Off by default (no-op).
-    constructor(session, { defaultTimeout, interval, log, backendTimeoutMs = 10000 }) {
+    constructor(session, { defaultTimeout, interval, log, backendTimeoutMs = 10000, caps = null }) {
         this.session = session;
         this.defaultTimeout = defaultTimeout;
         this.interval = interval;
         this.backendTimeoutMs = backendTimeoutMs;
+        this.caps = caps;
         this.log = typeof log === 'function' ? log : () => { };
     }
     locator(selector) { return new Locator(this, selector); }
@@ -617,7 +655,10 @@ export class Page {
         events flow through the same on()/waitForEvent listeners (each carries a
         monotonic `seq` for dedup). Resolves with the number of events replayed. */
     async replayEvents({ since = 0 } = {}) {
+        requireOp(this.caps, 'sink_replay', 'page.replayEvents()');
         const r = await this.session.request({ op: 'sink_replay', since });
+        if (!r.ok)
+            throw new Error(r.error || 'sink_replay failed');
         return r.count;
     }
     /** Poll a JS boolean expression in the page until it is truthy (or time out).
@@ -706,14 +747,17 @@ export class Page {
     })()`));
     }
     /** Capabilities handshake: { protocolVersion, platform, ops, screenshotAvailable,
-        authRequired }. Lets a caller branch on what the host supports (e.g. skip
-        screenshots when screenshotAvailable is false) without probing op-by-op. */
+        authRequired, moduleVersion? }. Lets a caller branch on what the host supports
+        (e.g. skip screenshots when screenshotAvailable is false) without probing
+        op-by-op. Returns the handshake connect() already took — it cannot change
+        within a connection — and only asks again if that one did not land. */
     async capabilities() {
-        const r = await this.session.request({ op: 'hello' });
-        return {
-            protocolVersion: r.protocolVersion, platform: r.platform, ops: r.ops,
-            screenshotAvailable: r.screenshotAvailable, authRequired: r.authRequired,
-        };
+        if (this.caps)
+            return this.caps;
+        const caps = await handshake(this.session);
+        if (!caps)
+            throw new Error('bridge did not answer the hello handshake');
+        return caps;
     }
     /** Toggle WebKit's compositing debug overlays (layer borders + repaint
         counters) on the host's WKWebView via the bridge `layerdebug` op. The
@@ -722,6 +766,7 @@ export class Page {
         macOS-only; throws where the backend has no such SPI. Remember to turn it
         OFF before any pixel-comparison capture: the overlays are pixels too. */
     async layerDebug(enabled = true) {
+        requireOp(this.caps, 'layerdebug', 'page.layerDebug()');
         this.log(`layerdebug ${enabled ? 'on' : 'off'}`);
         const r = await this.session.request({ op: 'layerdebug', enabled }, { timeoutMs: 10000 });
         if (!r.ok)
@@ -733,6 +778,7 @@ export class Page {
         to census compositing layers (count, geometry) from a script instead of
         reading overlay pixels off a screenshot. macOS-only; throws elsewhere. */
     async layerTree() {
+        requireOp(this.caps, 'layertree', 'page.layerTree()');
         this.log('layertree');
         const r = await this.session.request({ op: 'layertree' }, { timeoutMs: 10000 });
         if (!r.ok)
@@ -743,6 +789,7 @@ export class Page {
         Writes a PNG host-side and returns its path. Pass { path } to choose where, and
         { clip: {x,y,w,h} } (CSS px) to crop to a UI region for a much smaller PNG. */
     async screenshot({ path, clip } = {}) {
+        requireOp(this.caps, 'shot', 'page.screenshot()');
         this.log(`screenshot${clip ? ' (region)' : ''}${path ? ' ' + path : ''}`);
         const r = await this.session.request({ op: 'shot', ...(path ? { path } : {}), ...(clip ? { rect: clip } : {}) }, { timeoutMs: 30000 });
         if (!r.ok)

package/tools/shared.d.mts

@@ -7,6 +7,49 @@ export interface Discovery {
 /** 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;
+/** The protocol major these clients speak.
+ *
+ *  The npm client and the C++ module version independently: the plugin pins a
+ *  module tag in its build, the test host installs a client from npm, and the
+ *  two drift. Equal versions are NOT the goal — the protocol is additive, so an
+ *  older client against a newer module is fine by design. What matters is
+ *  capability negotiation, and the `hello` reply carries both halves of it:
+ *    - `ops`             — the fine-grained capability list (grows additively);
+ *    - `protocolVersion` — the coarse tripwire, moved ONLY by a breaking change.
+ *  So a host advertising a HIGHER protocolVersion is one this client predates. */
+export declare const CLIENT_PROTOCOL_VERSION = 1;
+/** The `hello` handshake. `moduleVersion` is absent on hosts built against a
+ *  module older than the release that started reporting it. */
+export interface BridgeCapabilities {
+    protocolVersion: number;
+    platform: string;
+    ops: string[];
+    screenshotAvailable: boolean;
+    authRequired: boolean;
+    moduleVersion?: string;
+}
+/** This npm client's own version, read from the package manifest so it cannot
+ *  drift from what was published. Falls back to 'unknown' — a diagnostic string
+ *  must never be the thing that throws. */
+export declare function clientVersion(): string;
+/** Normalize a `hello` reply into capabilities, or null when the reply is not a
+ *  usable handshake — i.e. a host too old to answer `hello` at all, which must
+ *  keep working with every guard standing down.
+ *
+ *  Deliberately total: it never throws and never inspects the transport. A
+ *  TRANSPORT failure is not a legacy host, so callers must let that propagate
+ *  rather than fold it into null — silently disabling the guards for the rest of
+ *  a connection is exactly the failure this negotiation exists to prevent.
+ *  Owning the parse here keeps the two clients from drifting apart. */
+export declare function parseHello(reply: Record<string, unknown> | null | undefined): BridgeCapabilities | null;
+/** Throw when the host speaks a protocol major this client cannot. Called once
+ *  per connection, right after the handshake. */
+export declare function assertProtocolSupported(caps: BridgeCapabilities): void;
+/** Throw an actionable error when the host bridge lacks the op an API needs.
+ *  Without this the host replies `unknown op: <x>`, which callers either surface
+ *  raw or (for ops whose reply is not checked) swallow into silently wrong
+ *  behaviour — neither of which points at the real cause: a stale module pin. */
+export declare function requireOp(caps: BridgeCapabilities | null, op: string, api: string): void;
 /** 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

package/tools/shared.mjs

@@ -3,7 +3,7 @@
  * 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.
+ * Still zero third-party dependencies: bare Node >= 22 built-ins only.
  */
 import fs from 'node:fs';
 import os from 'node:os';
@@ -12,6 +12,76 @@ 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;
+/** The protocol major these clients speak.
+ *
+ *  The npm client and the C++ module version independently: the plugin pins a
+ *  module tag in its build, the test host installs a client from npm, and the
+ *  two drift. Equal versions are NOT the goal — the protocol is additive, so an
+ *  older client against a newer module is fine by design. What matters is
+ *  capability negotiation, and the `hello` reply carries both halves of it:
+ *    - `ops`             — the fine-grained capability list (grows additively);
+ *    - `protocolVersion` — the coarse tripwire, moved ONLY by a breaking change.
+ *  So a host advertising a HIGHER protocolVersion is one this client predates. */
+export const CLIENT_PROTOCOL_VERSION = 1;
+/** This npm client's own version, read from the package manifest so it cannot
+ *  drift from what was published. Falls back to 'unknown' — a diagnostic string
+ *  must never be the thing that throws. */
+export function clientVersion() {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return manifest.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Normalize a `hello` reply into capabilities, or null when the reply is not a
+ *  usable handshake — i.e. a host too old to answer `hello` at all, which must
+ *  keep working with every guard standing down.
+ *
+ *  Deliberately total: it never throws and never inspects the transport. A
+ *  TRANSPORT failure is not a legacy host, so callers must let that propagate
+ *  rather than fold it into null — silently disabling the guards for the rest of
+ *  a connection is exactly the failure this negotiation exists to prevent.
+ *  Owning the parse here keeps the two clients from drifting apart. */
+export function parseHello(reply) {
+    if (!reply || reply.ok !== true || !Array.isArray(reply.ops))
+        return null;
+    return {
+        protocolVersion: Number(reply.protocolVersion),
+        platform: String(reply.platform),
+        ops: reply.ops,
+        screenshotAvailable: reply.screenshotAvailable === true,
+        authRequired: reply.authRequired === true,
+        ...(typeof reply.moduleVersion === 'string' ? { moduleVersion: reply.moduleVersion } : {}),
+    };
+}
+/** Identify both halves of the pairing for an error message. */
+function describePairing(caps) {
+    const host = caps.moduleVersion ?? 'version not reported (module predates moduleVersion)';
+    return `host module ${host}, protocol ${caps.protocolVersion}, ${caps.platform}; `
+        + `npm client ${clientVersion()}, protocol ${CLIENT_PROTOCOL_VERSION}`;
+}
+/** Throw when the host speaks a protocol major this client cannot. Called once
+ *  per connection, right after the handshake. */
+export function assertProtocolSupported(caps) {
+    if (!(caps.protocolVersion > CLIENT_PROTOCOL_VERSION))
+        return;
+    throw new Error(`bridge protocol ${caps.protocolVersion} is newer than this client understands `
+        + `(${CLIENT_PROTOCOL_VERSION}). The protocol major only moves on a BREAKING change, so this `
+        + `npm client is too old for the host's module — upgrade juce-webview-agent-bridge.\n  ${describePairing(caps)}`);
+}
+/** Throw an actionable error when the host bridge lacks the op an API needs.
+ *  Without this the host replies `unknown op: <x>`, which callers either surface
+ *  raw or (for ops whose reply is not checked) swallow into silently wrong
+ *  behaviour — neither of which points at the real cause: a stale module pin. */
+export function requireOp(caps, op, api) {
+    if (caps === null || caps.ops.includes(op))
+        return; // null = handshake unavailable; stay out of the way
+    throw new Error(`${api} needs the "${op}" op, which the host's juce_webview_agent_bridge module does not provide. `
+        + `The plugin was built against an older module than this client expects — bump its FetchContent `
+        + `GIT_TAG and rebuild the plugin.\n  ${describePairing(caps)}\n  host ops: ${caps.ops.join(', ')}`);
+}
 /** 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

package/tools/web-agent.mjs

@@ -25,7 +25,7 @@
  */
 import net from 'node:net';
 import path from 'node:path';
-import { DEFAULT_PORT, loadDiscovery, onJsonLines } from './shared.mjs';
+import { DEFAULT_PORT, assertProtocolSupported, loadDiscovery, onJsonLines, parseHello, requireOp } from './shared.mjs';
 const argv = process.argv.slice(2);
 const opt = (name, def) => {
     const i = argv.indexOf(name);
@@ -104,7 +104,31 @@ const fillSnippet = (sel, val) => `(() => {
   el.dispatchEvent(new Event('change', { bubbles: true }));
   return 'ok';
 })()`;
+// Commands that must survive a version mismatch instead of being blocked by it:
+// `ping` answers "is anything alive", and `hello` is the very tool you reach for
+// to SEE a mismatch. Refusing them on a protocol bump would remove the two
+// diagnostics you need most at exactly the moment you need them.
+const DIAGNOSTIC_CMDS = new Set(['ping', 'hello']);
+/** Negotiate once per CLI run: refuse a host whose protocol major is newer than
+    this client, and expose its op set to the per-command guards. Null means the
+    host is too old to answer `hello`, which must keep working untouched. */
+let hostCaps = null;
+async function negotiate() {
+    hostCaps = parseHello(await request({ op: 'hello' }));
+    if (hostCaps)
+        assertProtocolSupported(hostCaps);
+}
+/** Gate a command on an op the host may not have: without this an older module
+    answers `unknown op: <x>`, which reads as a client bug rather than the stale
+    module pin it actually is. */
+function requireHostOp(op, api) {
+    requireOp(hostCaps, op, api);
+}
 async function main() {
+    // One handshake per run, before any command runs: a host advertising a newer
+    // protocol major is refused here rather than half-served command by command.
+    if (cmd && !DIAGNOSTIC_CMDS.has(cmd))
+        await negotiate();
     switch (cmd) {
         case 'ping': {
             const r = await request({ op: 'ping' });
@@ -112,6 +136,7 @@ async function main() {
             break;
         }
         case 'layerdebug': {
+            requireHostOp('layerdebug', 'the `layerdebug` command');
             const enabled = rest[0] !== 'off';
             const r = await request({ op: 'layerdebug', enabled });
             console.log(r.ok
@@ -120,6 +145,7 @@ async function main() {
             break;
         }
         case 'layertree': {
+            requireHostOp('layertree', 'the `layertree` command');
             const r = await request({ op: 'layertree' });
             console.log(r.ok ? r.text : `failed: ${r.error || 'unavailable'}`);
             break;
@@ -127,7 +153,8 @@ async function main() {
         case 'hello': {
             const r = await request({ op: 'hello' });
             console.log(fmt({
-                protocolVersion: r.protocolVersion, platform: r.platform,
+                protocolVersion: r.protocolVersion, moduleVersion: r.moduleVersion ?? '(not reported)',
+                platform: r.platform,
                 screenshotAvailable: r.screenshotAvailable, authRequired: r.authRequired, ops: r.ops,
             }));
             break;
@@ -181,6 +208,7 @@ async function main() {
             // 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.
+            requireHostOp('shot', 'the `shot` command');
             const out = rest[0] ? path.resolve(rest[0]) : undefined;
             const sel = rest[1];
             let rect;