@bubblegum-ai/node 0.0.6-alpha.0

package/README.md

@@ -0,0 +1,144 @@
+# @bubblegum-ai/node
+
+Node/TypeScript client for [**Bubblegum**](https://github.com/bishnu133/bubblegum) —
+drive AI-powered, natural-language Playwright/Appium test steps from JS/TS.
+
+> **Status: alpha scaffold (`0.2.0` slice).** This is a thin, typed client that
+> spawns the Python **bubblegum bridge** and speaks its JSON-RPC protocol. The
+> Python engine stays the single source of truth for grounding/self-healing — we
+> do **not** re-implement it in TypeScript. See
+> [`docs/distribution-npm-and-pypi.md`](../../docs/distribution-npm-and-pypi.md)
+> and [`docs/bridge-protocol.md`](../../docs/bridge-protocol.md).
+
+## Prerequisites
+
+The client launches the engine as a child process, so a Python engine must be
+importable on the machine running your tests:
+
+```bash
+pip install "bubblegum-ai[web]"        # the engine + Playwright
+python -m playwright install chromium  # one-time browser download
+# (mobile: pip install "bubblegum-ai[mobile]" + a running Appium server/device)
+```
+
+Confirm the bridge is runnable:
+
+```bash
+python -m bubblegum.bridge   # should wait for JSON-RPC on stdin (Ctrl-D to exit)
+```
+
+## Install
+
+```bash
+npm install @bubblegum-ai/node
+```
+
+## Quick start
+
+```ts
+import { Bubblegum } from "@bubblegum-ai/node";
+
+const bg = await Bubblegum.launch({ url: "https://the-internet.herokuapp.com/login" });
+try {
+  await bg.act('Enter "tomsmith" into Username');
+  await bg.act('Enter "SuperSecretPassword!" into Password');
+  await bg.act("Click Login");
+  const r = await bg.verify("You logged into a secure area");
+  console.log(r.status); // "passed" | "recovered" | "failed"
+} finally {
+  await bg.close();
+}
+```
+
+`launch()` spawns the bridge, negotiates the protocol via `handshake`, and opens
+an **engine-owned** session (the Playwright `Page` / Appium driver lives in the
+Python process). Every method returns the same `StepResult` shape as the Python
+SDK.
+
+### Heal a stale selector (adoption path)
+
+```ts
+// old: await page.click("#login-btn");   // selector now stale
+const r = await bg.recover({ failedSelector: "#login-btn", intent: "Click Login" });
+// r.status === "recovered" when Bubblegum healed it
+```
+
+### Mobile
+
+```ts
+const bg = await Bubblegum.launch({
+  channel: "mobile",
+  appiumUrl: "http://127.0.0.1:4723",
+  capabilities: { platformName: "Android", "appium:app": "/path/to/app.apk" },
+});
+await bg.act("Tap Login");
+```
+
+### Attach to your own browser (CDP, client-owned)
+
+Instead of letting the engine launch its own Chromium, point it at the browser
+**your** Playwright test already drives, over the Chrome DevTools Protocol. Launch
+Chromium with a remote-debugging port, then `attach`:
+
+```ts
+import { chromium } from "@playwright/test";
+import { Bubblegum } from "@bubblegum-ai/node";
+
+const browser = await chromium.launch({ args: ["--remote-debugging-port=9222"] });
+const page = await browser.newPage();
+await page.goto("https://example.com/login");
+
+const bg = await Bubblegum.attach({ cdpEndpoint: "http://localhost:9222" });
+await bg.act("Click Login");   // drives the page you just opened
+await bg.close();              // disconnects; your browser keeps running
+```
+
+The engine attaches to an existing page (`pageIndex`, default 0) and never
+creates or closes your browser/page. Requires the engine to advertise the
+`channel.web.cdp` capability (Bubblegum ≥ 0.0.6); `attach()` throws a clear error
+otherwise. CDP attach is Chromium-only.
+
+## API
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `Bubblegum.launch(opts)` | `Promise<Bubblegum>` | spawn + handshake + `session.open` |
+| `bg.act(instruction, options?)` | `Promise<StepResult>` | |
+| `bg.verify(instruction, options?)` | `Promise<StepResult>` | |
+| `bg.extract(instruction, options?)` | `Promise<StepResult>` | value in `target.metadata.extracted_value` |
+| `bg.recover({ failedSelector, intent, options? })` | `Promise<StepResult>` | |
+| `bg.isVisible / isChecked / selectedValue(target)` | `Promise<boolean \| string>` | |
+| `bg.explain(instruction)` | `Promise<string>` | dry-run rationale |
+| `bg.summary()` | `Promise<SessionSummary>` | |
+| `bg.close()` | `Promise<void>` | closes the session + bridge |
+
+`options` is forwarded verbatim to the engine (`timeout_ms`, `selector`,
+`action_type`, `value`, `assertion_type`, `expected_value`, `max_cost_level`, …),
+matching the Python how-to guides.
+
+### Advanced: `BridgeClient`
+
+`Bubblegum` wraps a lower-level `BridgeClient` (`bg.bridge`) that you can use
+directly, or with an injected `Transport` (e.g. for tests or a future daemon
+socket). See `src/client.ts`.
+
+## Versioning
+
+The client pins to a compatible engine. It refuses to start against a
+`protocol_version` it doesn't support and tells you to upgrade — newer engines
+keep serving older clients (additive-first). This package's major/minor track the
+engine; install a matching `bubblegum-ai`.
+
+## Develop
+
+```bash
+npm install
+npm run build      # tsc -> dist/
+npm test           # build + node:test (no Python needed; mock transport)
+npm run typecheck
+```
+
+## Not yet (roadmap)
+
+- Auto-bootstrap of a managed Python venv when the engine isn't found.
+- Published to npm + dual-publish CI alongside PyPI.

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import { Handshake } from "./protocol.js";
+/**
+ * A line-oriented duplex link to the bridge. The default implementation spawns
+ * the Python `bubblegum bridge` process, but it is an interface so tests (and
+ * future transports — e.g. a long-lived daemon socket) can inject their own.
+ */
+export interface Transport {
+    /** Write one newline-delimited JSON-RPC message. */
+    send(line: string): void;
+    /** Register the handler for each inbound line. */
+    onLine(cb: (line: string) => void): void;
+    /** Register the handler invoked when the link closes (optionally with an error). */
+    onClose(cb: (err?: Error) => void): void;
+    /** Tear the link down. */
+    close(): Promise<void>;
+}
+export interface SpawnOptions {
+    /** Executable to launch (default: `python`). */
+    command?: string;
+    /** Args (default: `["-m", "bubblegum.bridge"]`). */
+    args?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** Spawn the Python bridge as a child process and frame JSON-RPC over its stdio. */
+export declare function spawnBridgeTransport(opts?: SpawnOptions): Transport;
+export interface BridgeClientOptions {
+    /** Inject a transport (tests/daemon). When omitted, a Python bridge is spawned. */
+    transport?: Transport;
+    /** Spawn options for the default transport. Ignored when `transport` is given. */
+    spawn?: SpawnOptions;
+}
+/**
+ * Low-level JSON-RPC client over a {@link Transport}: assigns request ids,
+ * correlates responses, surfaces engine errors as {@link BridgeError}, and
+ * negotiates the protocol version via {@link BridgeClient.handshake}.
+ */
+export declare class BridgeClient {
+    private readonly transport;
+    private readonly pending;
+    private nextId;
+    private closed;
+    /** Populated after a successful {@link handshake}. */
+    handshakeInfo?: Handshake;
+    constructor(opts?: BridgeClientOptions);
+    private onLine;
+    private onClose;
+    /** Issue a request and resolve with its `result` (or reject with a {@link BridgeError}). */
+    request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Negotiate with the engine; throws if its protocol version is unsupported. */
+    handshake(): Promise<Handshake>;
+    /** True if the engine advertised the given capability in its handshake. */
+    hasCapability(name: string): boolean;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,SAAS,EAIV,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kDAAkD;IAClD,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACzC,oFAAoF;IACpF,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACzC,0BAA0B;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,YAAiB,GAAG,SAAS,CA2BvE;AAOD,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kFAAkF;IAClF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,sDAAsD;IACtD,aAAa,CAAC,EAAE,SAAS,CAAC;gBAEd,IAAI,GAAE,mBAAwB;IAM1C,OAAO,CAAC,MAAM;IAoBd,OAAO,CAAC,OAAO;IAOf,4FAA4F;IAC5F,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAYtF,gFAAgF;IAC1E,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;IAarC,2EAA2E;IAC3E,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/client.js

@@ -0,0 +1,113 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { BridgeError } from "./errors.js";
+import { ErrorCodes, SUPPORTED_PROTOCOL_VERSIONS, isErrorResponse, } from "./protocol.js";
+/** Spawn the Python bridge as a child process and frame JSON-RPC over its stdio. */
+export function spawnBridgeTransport(opts = {}) {
+    const command = opts.command ?? "python";
+    const args = opts.args ?? ["-m", "bubblegum.bridge"];
+    const child = spawn(command, args, {
+        cwd: opts.cwd,
+        env: opts.env,
+        stdio: ["pipe", "pipe", "inherit"], // engine logs/errors pass through to our stderr
+    });
+    const rl = createInterface({ input: child.stdout });
+    return {
+        send(line) {
+            child.stdin.write(line + "\n");
+        },
+        onLine(cb) {
+            rl.on("line", cb);
+        },
+        onClose(cb) {
+            child.on("error", (err) => cb(err));
+            child.on("exit", () => cb());
+        },
+        async close() {
+            rl.close();
+            child.stdin.end();
+            if (child.exitCode === null)
+                child.kill();
+        },
+    };
+}
+/**
+ * Low-level JSON-RPC client over a {@link Transport}: assigns request ids,
+ * correlates responses, surfaces engine errors as {@link BridgeError}, and
+ * negotiates the protocol version via {@link BridgeClient.handshake}.
+ */
+export class BridgeClient {
+    transport;
+    pending = new Map();
+    nextId = 1;
+    closed = false;
+    /** Populated after a successful {@link handshake}. */
+    handshakeInfo;
+    constructor(opts = {}) {
+        this.transport = opts.transport ?? spawnBridgeTransport(opts.spawn);
+        this.transport.onLine((line) => this.onLine(line));
+        this.transport.onClose((err) => this.onClose(err));
+    }
+    onLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            return; // ignore non-JSON noise on the channel
+        }
+        if (typeof msg.id !== "number")
+            return; // we only issue numeric ids
+        const pending = this.pending.get(msg.id);
+        if (!pending)
+            return;
+        this.pending.delete(msg.id);
+        if (isErrorResponse(msg)) {
+            pending.reject(new BridgeError(msg.error.code, msg.error.message, msg.error.data));
+        }
+        else {
+            pending.resolve(msg.result);
+        }
+    }
+    onClose(err) {
+        this.closed = true;
+        const reason = err ?? new BridgeError(ErrorCodes.InternalError, "bridge connection closed");
+        for (const [, pending] of this.pending)
+            pending.reject(reason);
+        this.pending.clear();
+    }
+    /** Issue a request and resolve with its `result` (or reject with a {@link BridgeError}). */
+    request(method, params = {}) {
+        if (this.closed) {
+            return Promise.reject(new BridgeError(ErrorCodes.InternalError, "bridge is closed"));
+        }
+        const id = this.nextId++;
+        const payload = { jsonrpc: "2.0", id, method, params };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.transport.send(JSON.stringify(payload));
+        });
+    }
+    /** Negotiate with the engine; throws if its protocol version is unsupported. */
+    async handshake() {
+        const info = await this.request("handshake");
+        if (!SUPPORTED_PROTOCOL_VERSIONS.includes(info.protocol_version)) {
+            throw new BridgeError(ErrorCodes.Unsupported, `engine protocol v${info.protocol_version} is not supported by this client ` +
+                `(supports: ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")}). Upgrade @bubblegum-ai/node.`);
+        }
+        this.handshakeInfo = info;
+        return info;
+    }
+    /** True if the engine advertised the given capability in its handshake. */
+    hasCapability(name) {
+        return this.handshakeInfo?.capabilities.includes(name) ?? false;
+    }
+    async close() {
+        await this.transport.close();
+        this.onClose();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,UAAU,EAGV,2BAA2B,EAC3B,eAAe,GAChB,MAAM,eAAe,CAAC;AA2BvB,oFAAoF;AACpF,MAAM,UAAU,oBAAoB,CAAC,OAAqB,EAAE;IAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;QACjC,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,gDAAgD;KACrF,CAAC,CAAC;IACH,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAO,EAAE,CAAC,CAAC;IAErD,OAAO;QACL,IAAI,CAAC,IAAY;YACf,KAAK,CAAC,KAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,CAAC,EAA0B;YAC/B,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACpB,CAAC;QACD,OAAO,CAAC,EAAyB;YAC/B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACpC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,KAAK;YACT,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,CAAC,KAAM,CAAC,GAAG,EAAE,CAAC;YACnB,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;gBAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC;AAcD;;;;GAIG;AACH,MAAM,OAAO,YAAY;IACN,SAAS,CAAY;IACrB,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC9C,MAAM,GAAG,CAAC,CAAC;IACX,MAAM,GAAG,KAAK,CAAC;IACvB,sDAAsD;IACtD,aAAa,CAAa;IAE1B,YAAY,OAA4B,EAAE;QACxC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC;IAEO,MAAM,CAAC,IAAY;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,GAAoB,CAAC;QACzB,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,uCAAuC;QACjD,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;YAAE,OAAO,CAAC,4BAA4B;QACpE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACrF,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,WAAW,CAAC,UAAU,CAAC,aAAa,EAAE,0BAA0B,CAAC,CAAC;QAC5F,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/D,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,4FAA4F;IAC5F,OAAO,CAAc,MAAc,EAAE,SAAkC,EAAE;QACvE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,UAAU,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC,CAAC;QACvF,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,EAAE,OAAO,EAAE,KAAc,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAChE,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAA+B,EAAE,MAAM,EAAE,CAAC,CAAC;YAC3E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,SAAS;QACb,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAY,WAAW,CAAC,CAAC;QACxD,IAAI,CAAE,2BAAiD,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACxF,MAAM,IAAI,WAAW,CACnB,UAAU,CAAC,WAAW,EACtB,oBAAoB,IAAI,CAAC,gBAAgB,mCAAmC;gBAC1E,cAAc,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,gCAAgC,CACvF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2EAA2E;IAC3E,aAAa,CAAC,IAAY;QACxB,OAAO,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/** An error returned by the bridge (a JSON-RPC error response) or a transport failure. */
+export declare class BridgeError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAM1D"}

package/dist/errors.js

@@ -0,0 +1,12 @@
+/** An error returned by the bridge (a JSON-RPC error response) or a transport failure. */
+export class BridgeError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "BridgeError";
+        this.code = code;
+        this.data = data;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAS;IACb,IAAI,CAAW;IAExB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAc;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @bubblegum-ai/node — Node/TypeScript client for the Bubblegum engine.
+ *
+ * Drives AI-powered, natural-language Playwright/Appium test steps from JS/TS by
+ * spawning the Python `bubblegum bridge` and speaking its JSON-RPC protocol. The
+ * Python engine stays the single source of truth for grounding; this package is
+ * a thin, typed proxy. See ../../docs/distribution-npm-and-pypi.md.
+ */
+export { Bubblegum } from "./session.js";
+export type { Channel, LaunchOptions, AttachOptions, RecoverArgs } from "./session.js";
+export { BridgeClient, spawnBridgeTransport } from "./client.js";
+export type { Transport, SpawnOptions, BridgeClientOptions } from "./client.js";
+export { BridgeError } from "./errors.js";
+export { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, ErrorCodes, } from "./protocol.js";
+export type { Handshake, JsonRpcResponse } from "./protocol.js";
+export type { StepResult, StepStatus, ResolvedTarget, ErrorInfo, SessionSummary, StepOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEvF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhE,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,SAAS,EACT,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @bubblegum-ai/node — Node/TypeScript client for the Bubblegum engine.
+ *
+ * Drives AI-powered, natural-language Playwright/Appium test steps from JS/TS by
+ * spawning the Python `bubblegum bridge` and speaking its JSON-RPC protocol. The
+ * Python engine stays the single source of truth for grounding; this package is
+ * a thin, typed proxy. See ../../docs/distribution-npm-and-pypi.md.
+ */
+export { Bubblegum } from "./session.js";
+export { BridgeClient, spawnBridgeTransport } from "./client.js";
+export { BridgeError } from "./errors.js";
+export { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, ErrorCodes, } from "./protocol.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGjE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,UAAU,GACX,MAAM,eAAe,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Wire protocol for the Bubblegum bridge — the TypeScript mirror of
+ * `bubblegum/bridge/protocol.py`. Keep these in lockstep with the Python side.
+ *
+ * The client negotiates against the engine via `handshake`: it feature-detects
+ * on `capabilities` and refuses to run against a `protocol_version` it does not
+ * support, so a newer engine can keep serving an older client (additive-first).
+ */
+/** Protocol versions this client speaks. v1 = the 0.1.0 bridge slice. */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
+/** The latest protocol version this client was written against. */
+export declare const PROTOCOL_VERSION = 1;
+/** JSON-RPC 2.0 + bridge error codes (mirror of the Python side). */
+export declare const ErrorCodes: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly SessionNotFound: -32001;
+    readonly EngineError: -32002;
+    readonly Unsupported: -32003;
+};
+export type JsonRpcId = number | string | null;
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: JsonRpcId;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcSuccess {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcErrorResponse;
+export declare function isErrorResponse(msg: JsonRpcResponse): msg is JsonRpcErrorResponse;
+/** Result of the `handshake` method. */
+export interface Handshake {
+    engine_version: string;
+    protocol_version: number;
+    capabilities: string[];
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,cAAe,CAAC;AAExD,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,qEAAqE;AACrE,eAAO,MAAM,UAAU;;;;;;;;;CASb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D;AAED,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAEpE,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,GAAG,IAAI,oBAAoB,CAEjF;AAED,wCAAwC;AACxC,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB"}

package/dist/protocol.js

@@ -0,0 +1,27 @@
+/**
+ * Wire protocol for the Bubblegum bridge — the TypeScript mirror of
+ * `bubblegum/bridge/protocol.py`. Keep these in lockstep with the Python side.
+ *
+ * The client negotiates against the engine via `handshake`: it feature-detects
+ * on `capabilities` and refuses to run against a `protocol_version` it does not
+ * support, so a newer engine can keep serving an older client (additive-first).
+ */
+/** Protocol versions this client speaks. v1 = the 0.1.0 bridge slice. */
+export const SUPPORTED_PROTOCOL_VERSIONS = [1];
+/** The latest protocol version this client was written against. */
+export const PROTOCOL_VERSION = 1;
+/** JSON-RPC 2.0 + bridge error codes (mirror of the Python side). */
+export const ErrorCodes = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+    SessionNotFound: -32001,
+    EngineError: -32002,
+    Unsupported: -32003,
+};
+export function isErrorResponse(msg) {
+    return msg.error !== undefined;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,CAAU,CAAC;AAExD,mEAAmE;AACnE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,qEAAqE;AACrE,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,UAAU,EAAE,CAAC,KAAK;IAClB,cAAc,EAAE,CAAC,KAAK;IACtB,cAAc,EAAE,CAAC,KAAK;IACtB,aAAa,EAAE,CAAC,KAAK;IACrB,aAAa,EAAE,CAAC,KAAK;IACrB,eAAe,EAAE,CAAC,KAAK;IACvB,WAAW,EAAE,CAAC,KAAK;IACnB,WAAW,EAAE,CAAC,KAAK;CACX,CAAC;AAyBX,MAAM,UAAU,eAAe,CAAC,GAAoB;IAClD,OAAQ,GAA4B,CAAC,KAAK,KAAK,SAAS,CAAC;AAC3D,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,85 @@
+import { BridgeClient, BridgeClientOptions } from "./client.js";
+import { SessionSummary, StepOptions, StepResult } from "./types.js";
+export type Channel = "web" | "mobile";
+export interface LaunchOptions extends BridgeClientOptions {
+    /** "web" (default) or "mobile". */
+    channel?: Channel;
+    /** Web: start URL to open. */
+    url?: string;
+    /** Web: run headless (default true). */
+    headless?: boolean;
+    /** Resolve-only — never execute. */
+    dryRun?: boolean;
+    /** Mobile: Appium server URL (required for the mobile channel). */
+    appiumUrl?: string;
+    /** Mobile: Appium capabilities. */
+    capabilities?: Record<string, unknown>;
+    /**
+     * Web client-owned mode: attach the engine to an existing Chromium over CDP
+     * (e.g. `http://localhost:9222`) instead of launching one, so the engine
+     * drives the same browser your test already controls. Requires the engine to
+     * advertise the `channel.web.cdp` capability.
+     */
+    cdpEndpoint?: string;
+    /** Which existing page to attach to when using `cdpEndpoint` (default 0). */
+    pageIndex?: number;
+}
+/** Options for {@link Bubblegum.attach} — `cdpEndpoint` is required. */
+export interface AttachOptions extends Omit<LaunchOptions, "channel"> {
+    cdpEndpoint: string;
+}
+export interface RecoverArgs {
+    failedSelector: string;
+    intent: string;
+    options?: StepOptions;
+}
+/**
+ * The ergonomic, engine-owned session. `launch()` spawns the bridge, negotiates
+ * the protocol, and opens a session whose Playwright/Appium handle lives inside
+ * the Python engine; every call here is a thin proxy to the same four primitives
+ * the Python SDK exposes, returning the identical `StepResult` shape.
+ *
+ * ```ts
+ * const bg = await Bubblegum.launch({ url: "https://example.com/login" });
+ * try {
+ *   await bg.act('Enter "tom" into Username');
+ *   await bg.act("Click Login");
+ *   await bg.verify("Dashboard is visible");
+ * } finally {
+ *   await bg.close();
+ * }
+ * ```
+ */
+export declare class Bubblegum {
+    private readonly client;
+    private readonly sessionId;
+    private constructor();
+    /** Spawn the bridge, handshake, and open a session (engine-owned by default). */
+    static launch(opts?: LaunchOptions): Promise<Bubblegum>;
+    /**
+     * Attach the engine to a browser your test already controls, over CDP
+     * (client-owned mode). Launch your Chromium with a remote-debugging port and
+     * pass its endpoint:
+     *
+     * ```ts
+     * const browser = await chromium.launch({ args: ["--remote-debugging-port=9222"] });
+     * const bg = await Bubblegum.attach({ cdpEndpoint: "http://localhost:9222" });
+     * await bg.act("Click Login"); // drives the page your test opened
+     * ```
+     */
+    static attach(opts: AttachOptions): Promise<Bubblegum>;
+    /** The bridge client (for advanced use / capability checks). */
+    get bridge(): BridgeClient;
+    act(instruction: string, options?: StepOptions): Promise<StepResult>;
+    verify(instruction: string, options?: StepOptions): Promise<StepResult>;
+    extract(instruction: string, options?: StepOptions): Promise<StepResult>;
+    recover(args: RecoverArgs): Promise<StepResult>;
+    isVisible(target: string): Promise<boolean>;
+    isChecked(target: string): Promise<boolean>;
+    selectedValue(target: string): Promise<string>;
+    explain(instruction: string): Promise<string>;
+    summary(): Promise<SessionSummary>;
+    /** Close the engine session and tear down the bridge process. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEvC,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACxD,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC;IACnE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAF5B,OAAO;IAKP,iFAAiF;WACpE,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,SAAS,CAAC;IA2BjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IAItD,gEAAgE;IAChE,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQpE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQvE,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQxE,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IASzC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3C,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ9C,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQnD,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;IAIlC,iEAAiE;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/session.js

@@ -0,0 +1,141 @@
+import { BridgeClient } from "./client.js";
+import { BridgeError } from "./errors.js";
+import { ErrorCodes } from "./protocol.js";
+/**
+ * The ergonomic, engine-owned session. `launch()` spawns the bridge, negotiates
+ * the protocol, and opens a session whose Playwright/Appium handle lives inside
+ * the Python engine; every call here is a thin proxy to the same four primitives
+ * the Python SDK exposes, returning the identical `StepResult` shape.
+ *
+ * ```ts
+ * const bg = await Bubblegum.launch({ url: "https://example.com/login" });
+ * try {
+ *   await bg.act('Enter "tom" into Username');
+ *   await bg.act("Click Login");
+ *   await bg.verify("Dashboard is visible");
+ * } finally {
+ *   await bg.close();
+ * }
+ * ```
+ */
+export class Bubblegum {
+    client;
+    sessionId;
+    constructor(client, sessionId) {
+        this.client = client;
+        this.sessionId = sessionId;
+    }
+    /** Spawn the bridge, handshake, and open a session (engine-owned by default). */
+    static async launch(opts = {}) {
+        const client = new BridgeClient(opts);
+        try {
+            await client.handshake();
+            if (opts.cdpEndpoint && !client.hasCapability("channel.web.cdp")) {
+                throw new BridgeError(ErrorCodes.Unsupported, "this engine does not support CDP attach (channel.web.cdp); upgrade bubblegum-ai");
+            }
+            const { session_id } = await client.request("session.open", {
+                channel: opts.channel ?? "web",
+                url: opts.url,
+                headless: opts.headless ?? true,
+                dry_run: opts.dryRun ?? false,
+                appium_url: opts.appiumUrl,
+                capabilities: opts.capabilities,
+                cdp_endpoint: opts.cdpEndpoint,
+                page_index: opts.pageIndex,
+            });
+            return new Bubblegum(client, session_id);
+        }
+        catch (err) {
+            await client.close();
+            throw err;
+        }
+    }
+    /**
+     * Attach the engine to a browser your test already controls, over CDP
+     * (client-owned mode). Launch your Chromium with a remote-debugging port and
+     * pass its endpoint:
+     *
+     * ```ts
+     * const browser = await chromium.launch({ args: ["--remote-debugging-port=9222"] });
+     * const bg = await Bubblegum.attach({ cdpEndpoint: "http://localhost:9222" });
+     * await bg.act("Click Login"); // drives the page your test opened
+     * ```
+     */
+    static attach(opts) {
+        return Bubblegum.launch({ ...opts, channel: "web" });
+    }
+    /** The bridge client (for advanced use / capability checks). */
+    get bridge() {
+        return this.client;
+    }
+    act(instruction, options) {
+        return this.client.request("act", {
+            session_id: this.sessionId,
+            instruction,
+            options,
+        });
+    }
+    verify(instruction, options) {
+        return this.client.request("verify", {
+            session_id: this.sessionId,
+            instruction,
+            options,
+        });
+    }
+    extract(instruction, options) {
+        return this.client.request("extract", {
+            session_id: this.sessionId,
+            instruction,
+            options,
+        });
+    }
+    recover(args) {
+        return this.client.request("recover", {
+            session_id: this.sessionId,
+            failed_selector: args.failedSelector,
+            intent: args.intent,
+            options: args.options,
+        });
+    }
+    async isVisible(target) {
+        const r = await this.client.request("is_visible", {
+            session_id: this.sessionId,
+            target,
+        });
+        return r.value;
+    }
+    async isChecked(target) {
+        const r = await this.client.request("is_checked", {
+            session_id: this.sessionId,
+            target,
+        });
+        return r.value;
+    }
+    async selectedValue(target) {
+        const r = await this.client.request("selected_value", {
+            session_id: this.sessionId,
+            target,
+        });
+        return r.value;
+    }
+    async explain(instruction) {
+        const r = await this.client.request("explain", {
+            session_id: this.sessionId,
+            instruction,
+        });
+        return r.explanation;
+    }
+    summary() {
+        return this.client.request("summary", { session_id: this.sessionId });
+    }
+    /** Close the engine session and tear down the bridge process. */
+    async close() {
+        try {
+            await this.client.request("session.close", { session_id: this.sessionId });
+        }
+        finally {
+            await this.client.close();
+        }
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * TypeScript mirror of the engine's result schemas (`bubblegum/core/schemas.py`).
+ *
+ * Kept intentionally close to the Pydantic models. `[key: string]: unknown`
+ * index signatures let newer engine fields flow through without breaking the
+ * client (additive-first), while the named fields stay strongly typed.
+ */
+export type StepStatus = "passed" | "failed" | "recovered" | "dry_run" | "skipped";
+export interface ResolvedTarget {
+    ref: string;
+    confidence: number;
+    resolver_name: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ErrorInfo {
+    error_type: string;
+    message: string;
+    resolver_name?: string | null;
+    [key: string]: unknown;
+}
+export interface StepResult {
+    status: StepStatus;
+    action: string;
+    target: ResolvedTarget | null;
+    confidence: number;
+    duration_ms: number;
+    error?: ErrorInfo | null;
+    traces?: unknown[];
+    [key: string]: unknown;
+}
+export interface SessionSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    [key: string]: unknown;
+}
+/** Per-call options forwarded verbatim to the engine SDK (timeout_ms, selector, …). */
+export type StepOptions = Record<string, unknown>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnF,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * TypeScript mirror of the engine's result schemas (`bubblegum/core/schemas.py`).
+ *
+ * Kept intentionally close to the Pydantic models. `[key: string]: unknown`
+ * index signatures let newer engine fields flow through without breaking the
+ * client (additive-first), while the named fields stay strongly typed.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@bubblegum-ai/node",
+  "version": "0.0.6-alpha.0",
+  "description": "Node/TypeScript client for the Bubblegum engine — drive AI-powered, natural-language Playwright/Appium test steps from JS/TS via the Bubblegum JSON-RPC bridge.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "bubblegum",
+    "playwright",
+    "appium",
+    "testing",
+    "test-automation",
+    "self-healing",
+    "natural-language",
+    "ai"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bishnu133/bubblegum.git",
+    "directory": "clients/node"
+  },
+  "homepage": "https://github.com/bishnu133/bubblegum/tree/main/clients/node",
+  "bugs": {
+    "url": "https://github.com/bishnu133/bubblegum/issues"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}