@melra/browser-runtime 0.3.0-alpha.10

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.10",
+  "description": "Browser reference effect adapter for the MELRA kernel.",
+  "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.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run --testTimeout=60000 --hookTimeout=60000",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}