@melra/browser-runtime 0.3.0-alpha.3

package/dist/see-act.test.js

@@ -0,0 +1,152 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { createServer } from "node:http";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BrowserOperationSchema } from "@melra/protocol";
+import { afterEach, describe, expect, it } from "vitest";
+import { BrowserRuntime, detectBrowserExecutable } from "./index.js";
+/**
+ * The see/act loop is the thing that was broken: a caller could read a snapshot
+ * but had no way to turn what it saw into a target it could act on. These tests
+ * drive a real page, so they fail if the emitted selector does not address the
+ * element it was reported for.
+ */
+const PAGE = `<!doctype html><html><head><title>See act</title></head><body>
+  <form id="login">
+    <input name="email" placeholder="Email">
+    <input name="password" type="password">
+    <button type="submit" data-testid="submit"> Sign in </button>
+  </form>
+  <div><span>Total</span><section id="cart"><p>2 items</p></section></div>
+  <button disabled>Locked</button>
+</body></html>`;
+const roots = [];
+const servers = [];
+afterEach(async () => {
+    await Promise.all(servers.splice(0).map((server) => new Promise((done) => {
+        server.close(() => done());
+    })));
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+async function fixture() {
+    const executablePath = await detectBrowserExecutable();
+    if (executablePath === undefined)
+        return undefined;
+    const server = createServer((_request, response) => {
+        response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        response.end(PAGE);
+    });
+    servers.push(server);
+    await new Promise((done) => {
+        server.listen(0, "127.0.0.1", done);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("fixture_server_address_unavailable");
+    }
+    const root = await mkdtemp(join(tmpdir(), "melra-see-act-"));
+    roots.push(root);
+    return {
+        runtime: new BrowserRuntime({
+            workspaceRoot: root,
+            artifactDirectory: join(root, "artifacts"),
+            executablePath,
+            allowedDomains: ["127.0.0.1"],
+            allowLocalhost: true,
+        }),
+        url: `http://127.0.0.1:${address.port}`,
+    };
+}
+describe("browser see/act loop", () => {
+    it("emits a selector that addresses the element it was reported for", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            const observed = await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            const elements = observed.elements;
+            const submit = elements.find((item) => item.testId === "submit");
+            expect(submit?.selector).toBe('[data-testid="submit"]');
+            const email = elements.find((item) => item.attributeName === "email");
+            // Anchored on the form's id rather than a path from <html>.
+            expect(email?.selector).toBe("#login > input:nth-child(1)");
+            expect(email?.placeholder).toBe("Email");
+            expect(elements.find((item) => item.name === "Locked")?.disabled).toBe(true);
+            expect(elements.every((item) => typeof item.index === "number")).toBe(true);
+            // The loop closes only if the selector can be acted on.
+            const typed = await runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "type",
+                target: { selector: email.selector },
+                value: "user@example.com",
+            }));
+            expect(typed.typed).toBe(true);
+            const after = (await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "inspect" }))).elements.find((item) => item.attributeName === "email");
+            expect(after?.value).toBe("user@example.com");
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+    it("matches text through surrounding whitespace instead of failing exact", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            // `<button> Sign in </button>` never matched `getByText("Sign in", {exact:true})`.
+            const clicked = await runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "click",
+                target: { text: "Sign in" },
+            }));
+            expect(clicked.clicked).toBe(true);
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+    it("reports a target that matches nothing instead of timing out opaquely", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            await expect(runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "click",
+                target: { selector: "#nothing-here" },
+                timeoutMs: 120_000,
+            }))).rejects.toThrow("browser_target_not_found");
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+    it("scopes extraction to a target rather than returning the whole page", async () => {
+        const context = await fixture();
+        if (context === undefined)
+            return;
+        const { runtime, url } = context;
+        try {
+            await runtime.execute(BrowserOperationSchema.parse({ kind: "browser", action: "navigate", url }));
+            const extracted = await runtime.execute(BrowserOperationSchema.parse({
+                kind: "browser",
+                action: "inspect",
+                target: { selector: "#cart" },
+            }));
+            expect(extracted.text).toBe("2 items");
+            expect(extracted.html).toBe("<p>2 items</p>");
+            expect(extracted.text).not.toContain("Total");
+        }
+        finally {
+            await runtime.close();
+        }
+    }, 120_000);
+});
+//# sourceMappingURL=see-act.test.js.map

package/dist/see-act.test.js.map

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

package/dist/selector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One ancestor step on the path from an anchor down to a snapshot element.
+ *
+ * The page collects these as plain data and the selector string is assembled
+ * here, in Node, so the interesting logic is a pure function of plain objects
+ * and can be tested without a DOM.
+ */
+export interface ElementDescriptor {
+    tag: string;
+    /** 1-based position among the parent's element children. */
+    nth: number;
+    id?: string;
+    testId?: string;
+}
+/**
+ * Assemble a CSS selector addressing the element the chain ends at.
+ *
+ * `snapshot` previously reported `{tag, role, name, type}` and nothing else,
+ * which left a caller no way to turn something it had just seen into something
+ * it could act on — the only remaining option was `getByText(..., {exact: true})`,
+ * which breaks on whitespace, casing, and nested markup. Emitting a selector
+ * alongside each element closes that loop.
+ *
+ * The chain runs anchor-first. Collection stops as soon as it reaches an element
+ * carrying an `id` or `data-testid`, so a page that labels its markup produces a
+ * short, re-render-durable selector; a page that does not falls back to a
+ * positional path, which is exact for the snapshot it came from.
+ */
+export declare function buildSelector(chain: ElementDescriptor[]): string;
+//# sourceMappingURL=selector.d.ts.map

package/dist/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAehE"}

package/dist/selector.js

@@ -0,0 +1,39 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+/** CSS identifiers may not start with a digit and may not contain punctuation. */
+const PLAIN_IDENTIFIER = /^[A-Za-z_-][\w-]*$/;
+function attributeValue(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+/**
+ * Assemble a CSS selector addressing the element the chain ends at.
+ *
+ * `snapshot` previously reported `{tag, role, name, type}` and nothing else,
+ * which left a caller no way to turn something it had just seen into something
+ * it could act on — the only remaining option was `getByText(..., {exact: true})`,
+ * which breaks on whitespace, casing, and nested markup. Emitting a selector
+ * alongside each element closes that loop.
+ *
+ * The chain runs anchor-first. Collection stops as soon as it reaches an element
+ * carrying an `id` or `data-testid`, so a page that labels its markup produces a
+ * short, re-render-durable selector; a page that does not falls back to a
+ * positional path, which is exact for the snapshot it came from.
+ */
+export function buildSelector(chain) {
+    if (chain.length === 0)
+        throw new Error("browser_selector_requires_chain");
+    return chain
+        .map((step) => {
+        if (step.id !== undefined) {
+            return PLAIN_IDENTIFIER.test(step.id)
+                ? `#${step.id}`
+                : `[id="${attributeValue(step.id)}"]`;
+        }
+        if (step.testId !== undefined) {
+            return `[data-testid="${attributeValue(step.testId)}"]`;
+        }
+        return `${step.tag}:nth-child(${step.nth})`;
+    })
+        .join(" > ");
+}
+//# sourceMappingURL=selector.js.map

package/dist/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC;AAiBtC,kFAAkF;AAClF,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAE9C,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,KAA0B;IACtD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC3E,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,EAAE;gBACf,CAAC,CAAC,QAAQ,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;QAC1C,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,iBAAiB,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QAC1D,CAAC;QACD,OAAO,GAAG,IAAI,CAAC,GAAG,cAAc,IAAI,CAAC,GAAG,GAAG,CAAC;IAC9C,CAAC,CAAC;SACD,IAAI,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}

package/dist/selector.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=selector.test.d.ts.map

package/dist/selector.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.test.d.ts","sourceRoot":"","sources":["../src/selector.test.ts"],"names":[],"mappings":""}

package/dist/selector.test.js

@@ -0,0 +1,34 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from "vitest";
+import { buildSelector } from "./selector.js";
+describe("buildSelector", () => {
+    it("anchors on an id when the page provides one", () => {
+        expect(buildSelector([
+            { tag: "form", nth: 2, id: "login" },
+            { tag: "input", nth: 3 },
+        ])).toBe("#login > input:nth-child(3)");
+    });
+    it("prefers a test id over positional descent", () => {
+        expect(buildSelector([
+            { tag: "div", nth: 1, testId: "cart" },
+            { tag: "button", nth: 2 },
+        ])).toBe('[data-testid="cart"] > button:nth-child(2)');
+    });
+    it("falls back to a positional path when nothing is labelled", () => {
+        expect(buildSelector([
+            { tag: "html", nth: 1 },
+            { tag: "body", nth: 2 },
+            { tag: "a", nth: 5 },
+        ])).toBe("html:nth-child(1) > body:nth-child(2) > a:nth-child(5)");
+    });
+    it("quotes an id that is not a bare CSS identifier", () => {
+        // Frameworks emit ids like `:r1:` and `user.email`, which `#id` cannot spell.
+        expect(buildSelector([{ tag: "input", nth: 1, id: ":r1:" }])).toBe('[id=":r1:"]');
+        expect(buildSelector([{ tag: "input", nth: 1, id: 'a"b' }])).toBe('[id="a\\"b"]');
+    });
+    it("refuses an empty chain rather than emitting a selector matching everything", () => {
+        expect(() => buildSelector([])).toThrow("browser_selector_requires_chain");
+    });
+});
+//# sourceMappingURL=selector.test.js.map

package/dist/selector.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.test.js","sourceRoot":"","sources":["../src/selector.test.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,CACJ,aAAa,CAAC;YACZ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE;YACpC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE;SACzB,CAAC,CACH,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,MAAM,CACJ,aAAa,CAAC;YACZ,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE;YACtC,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE;SAC1B,CAAC,CACH,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,CACJ,aAAa,CAAC;YACZ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE;YACvB,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE;YACvB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE;SACrB,CAAC,CACH,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,8EAA8E;QAC9E,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAChE,aAAa,CACd,CAAC;QACF,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAC/D,cAAc,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4EAA4E,EAAE,GAAG,EAAE;QACpF,MAAM,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,iCAAiC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/stable-dom.d.ts

@@ -0,0 +1,21 @@
+import type { Page } from "playwright-core";
+export interface DomStabilityOptions {
+    quietWindowMs?: number;
+    timeoutMs?: number;
+}
+export interface DomStabilityResult {
+    waitedMs: number;
+    mutationCount: number;
+    timedOut: boolean;
+    reason: "quiet_window" | "timeout" | "page_unavailable";
+}
+export declare function normalizeDomStabilityOptions(options?: DomStabilityOptions): Required<DomStabilityOptions>;
+/**
+ * Wait until DOM mutations have been quiet for a bounded window.
+ *
+ * This is intentionally condition-based instead of a fixed sleep. It returns
+ * its own measurement so callers can distinguish a stable observation from a
+ * timeout and preserve that distinction in execution evidence.
+ */
+export declare function waitForStableDom(page: Page, options?: DomStabilityOptions): Promise<DomStabilityResult>;
+//# sourceMappingURL=stable-dom.d.ts.map

package/dist/stable-dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-dom.d.ts","sourceRoot":"","sources":["../src/stable-dom.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,kBAAkB,CAAC;CACzD;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,mBAAwB,GAChC,QAAQ,CAAC,mBAAmB,CAAC,CAU/B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAqE7B"}

package/dist/stable-dom.js

@@ -0,0 +1,76 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+export function normalizeDomStabilityOptions(options = {}) {
+    const quietWindowMs = Math.max(25, Math.min(2_000, Math.round(options.quietWindowMs ?? 180)));
+    const timeoutMs = Math.max(quietWindowMs, Math.min(10_000, Math.round(options.timeoutMs ?? 1_500)));
+    return { quietWindowMs, timeoutMs };
+}
+/**
+ * Wait until DOM mutations have been quiet for a bounded window.
+ *
+ * This is intentionally condition-based instead of a fixed sleep. It returns
+ * its own measurement so callers can distinguish a stable observation from a
+ * timeout and preserve that distinction in execution evidence.
+ */
+export async function waitForStableDom(page, options = {}) {
+    if (page.isClosed()) {
+        return {
+            waitedMs: 0,
+            mutationCount: 0,
+            timedOut: false,
+            reason: "page_unavailable",
+        };
+    }
+    const normalized = normalizeDomStabilityOptions(options);
+    try {
+        return await page.evaluate(({ quietWindowMs, timeoutMs }) => new Promise((resolve) => {
+            const startedAt = performance.now();
+            let mutations = 0;
+            let quietTimer;
+            let timeoutTimer;
+            let settled = false;
+            const finish = (reason, timedOut) => {
+                if (settled)
+                    return;
+                settled = true;
+                observer.disconnect();
+                if (quietTimer !== undefined)
+                    clearTimeout(quietTimer);
+                if (timeoutTimer !== undefined)
+                    clearTimeout(timeoutTimer);
+                resolve({
+                    waitedMs: Math.round(performance.now() - startedAt),
+                    mutationCount: mutations,
+                    timedOut,
+                    reason,
+                });
+            };
+            const armQuietWindow = () => {
+                if (quietTimer !== undefined)
+                    clearTimeout(quietTimer);
+                quietTimer = setTimeout(() => finish("quiet_window", false), quietWindowMs);
+            };
+            const observer = new MutationObserver((records) => {
+                mutations += records.length;
+                armQuietWindow();
+            });
+            observer.observe(document.documentElement, {
+                attributes: true,
+                characterData: true,
+                childList: true,
+                subtree: true,
+            });
+            timeoutTimer = setTimeout(() => finish("timeout", true), timeoutMs);
+            armQuietWindow();
+        }), normalized);
+    }
+    catch {
+        return {
+            waitedMs: 0,
+            mutationCount: 0,
+            timedOut: false,
+            reason: "page_unavailable",
+        };
+    }
+}
+//# sourceMappingURL=stable-dom.js.map

package/dist/stable-dom.js.map

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

package/dist/stable-dom.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stable-dom.test.d.ts.map

package/dist/stable-dom.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-dom.test.d.ts","sourceRoot":"","sources":["../src/stable-dom.test.ts"],"names":[],"mappings":""}

package/dist/stable-dom.test.js

@@ -0,0 +1,22 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from "vitest";
+import { normalizeDomStabilityOptions } from "./stable-dom.js";
+describe("DOM stability options", () => {
+    it("applies bounded defaults", () => {
+        expect(normalizeDomStabilityOptions()).toEqual({
+            quietWindowMs: 180,
+            timeoutMs: 1_500,
+        });
+    });
+    it("keeps the timeout at or above the quiet window", () => {
+        expect(normalizeDomStabilityOptions({
+            quietWindowMs: 900,
+            timeoutMs: 100,
+        })).toEqual({
+            quietWindowMs: 900,
+            timeoutMs: 900,
+        });
+    });
+});
+//# sourceMappingURL=stable-dom.test.js.map

package/dist/stable-dom.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-dom.test.js","sourceRoot":"","sources":["../src/stable-dom.test.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAE/D,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC;YAC7C,aAAa,EAAE,GAAG;YAClB,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,CACJ,4BAA4B,CAAC;YAC3B,aAAa,EAAE,GAAG;YAClB,SAAS,EAAE,GAAG;SACf,CAAC,CACH,CAAC,OAAO,CAAC;YACR,aAAa,EAAE,GAAG;YAClB,SAAS,EAAE,GAAG;SACf,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@melra/browser-runtime",
+  "version": "0.3.0-alpha.3",
+  "description": "Policy-governed browser automation runtime for MELRA.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XAGI-Lab/melra.git",
+    "directory": "packages/browser-runtime"
+  },
+  "homepage": "https://github.com/XAGI-Lab/melra#readme",
+  "bugs": "https://github.com/XAGI-Lab/melra/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "playwright-core": "1.62.0",
+    "@melra/protocol": "0.3.0-alpha.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run --testTimeout=60000 --hookTimeout=60000",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}