@volter-ai-dev/supercode-browser-playwright 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1016 @@
+// src/executor.ts
+import { errors } from "playwright-core";
+
+// src/protocol.ts
+var SUPERCODE_BROWSER_PROVIDER_PROTOCOL = "supercode/browser-provider-v1";
+var SUPERCODE_BROWSER_OPERATION_PROTOCOL = "supercode/browser-operation-v1";
+var BROWSER_OPERATION_NAMES = Object.freeze([
+  "browser.status",
+  "browser.snapshot",
+  "browser.query",
+  "browser.wait",
+  "browser.click",
+  "browser.fill",
+  "browser.press",
+  "browser.hover",
+  "browser.focus",
+  "browser.check",
+  "browser.uncheck",
+  "browser.select",
+  "browser.scroll",
+  "browser.back",
+  "browser.forward",
+  "browser.reload",
+  "browser.box",
+  "browser.mouse",
+  "browser.drag",
+  "browser.wheel",
+  "browser.script"
+]);
+var OPERATION_NAMES = new Set(BROWSER_OPERATION_NAMES);
+var BrowserActionRefusal = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BrowserActionRefusal";
+  }
+};
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function exactKeys(candidate, allowed) {
+  return Object.keys(candidate).every((key) => allowed.includes(key));
+}
+function parsePage(value) {
+  return value === void 0 ? void 0 : typeof value === "string" && value.length > 0 && value.length <= 512 ? value : null;
+}
+function parseBrowserLocator(value) {
+  const candidate = record(value);
+  if (!candidate || typeof candidate.by !== "string") return null;
+  if (candidate.by === "label" || candidate.by === "placeholder" || candidate.by === "altText" || candidate.by === "title") {
+    const { by, text, exact } = candidate;
+    return typeof text === "string" && (exact === void 0 || typeof exact === "boolean") && exactKeys(candidate, ["by", "text", "exact"]) ? { by, text, ...exact !== void 0 ? { exact } : {} } : null;
+  }
+  if (candidate.by === "css" || candidate.by === "ref" || candidate.by === "testId") {
+    return exactKeys(candidate, ["by", "value"]) && typeof candidate.value === "string" && candidate.value.length > 0 && candidate.value.length <= 2e3 ? { by: candidate.by, value: candidate.value } : null;
+  }
+  if (candidate.by === "role") {
+    if (!exactKeys(candidate, ["by", "role", "name", "exact"]) || typeof candidate.role !== "string" || !candidate.role || candidate.name !== void 0 && typeof candidate.name !== "string" || candidate.exact !== void 0 && typeof candidate.exact !== "boolean") return null;
+    return {
+      by: "role",
+      role: candidate.role,
+      ...typeof candidate.name === "string" ? { name: candidate.name } : {},
+      ...typeof candidate.exact === "boolean" ? { exact: candidate.exact } : {}
+    };
+  }
+  if (candidate.by === "text") {
+    if (!exactKeys(candidate, ["by", "text", "exact"]) || typeof candidate.text !== "string" || !candidate.text || candidate.exact !== void 0 && typeof candidate.exact !== "boolean") return null;
+    return {
+      by: "text",
+      text: candidate.text,
+      ...typeof candidate.exact === "boolean" ? { exact: candidate.exact } : {}
+    };
+  }
+  return null;
+}
+function parseTargetInput(value, options) {
+  const candidate = record(value);
+  if (!candidate) return null;
+  const allowed = ["page", "locator", "index", "expectedRevision"];
+  if (options.value) allowed.push("value");
+  if (options.values) allowed.push("values");
+  if (options.key) allowed.push("key");
+  if (options.wait) allowed.push("state", "timeout");
+  if (!exactKeys(candidate, allowed)) return null;
+  const page = parsePage(candidate.page);
+  const locator = candidate.locator === void 0 ? void 0 : parseBrowserLocator(candidate.locator);
+  const index = candidate.index;
+  const revision = candidate.expectedRevision;
+  if (page === null || options.locatorRequired && !locator || candidate.locator !== void 0 && !locator || index !== void 0 && (!Number.isInteger(index) || index < 0) || revision !== void 0 && (!Number.isInteger(revision) || revision < 0) || options.value && typeof candidate.value !== "string" || options.values && (!Array.isArray(candidate.values) || !candidate.values.every((item) => typeof item === "string")) || options.key && (typeof candidate.key !== "string" || !candidate.key || candidate.key.length > 100) || options.wait && candidate.state !== void 0 && candidate.state !== "attached" && candidate.state !== "visible" || options.wait && candidate.timeout !== void 0 && (typeof candidate.timeout !== "number" || candidate.timeout < 0 || candidate.timeout > 3e4)) return null;
+  return {
+    ...page ? { page } : {},
+    ...locator ? { locator } : {},
+    ...typeof index === "number" ? { index } : {},
+    ...typeof revision === "number" ? { expectedRevision: revision } : {},
+    ...options.value ? { value: candidate.value } : {},
+    ...options.values ? { values: candidate.values } : {},
+    ...options.key ? { key: candidate.key } : {},
+    ...options.wait && candidate.state ? { state: candidate.state } : {},
+    ...options.wait && typeof candidate.timeout === "number" ? { timeout: candidate.timeout } : {}
+  };
+}
+function parseBrowserOperationInput(operation, value) {
+  const candidate = record(value);
+  if (!candidate) return null;
+  if (operation === "browser.status") return exactKeys(candidate, []) ? {} : null;
+  if (operation === "browser.snapshot") {
+    const page = parsePage(candidate.page);
+    const locator = candidate.locator === void 0 ? void 0 : parseBrowserLocator(candidate.locator);
+    return exactKeys(candidate, ["page", "locator"]) && page !== null && (candidate.locator === void 0 || locator !== null) ? { ...page ? { page } : {}, ...locator ? { locator } : {} } : null;
+  }
+  if (operation === "browser.query" || operation === "browser.click" || operation === "browser.hover" || operation === "browser.focus" || operation === "browser.check" || operation === "browser.uncheck") {
+    return parseTargetInput(candidate, { locatorRequired: true });
+  }
+  if (operation === "browser.wait")
+    return parseTargetInput(candidate, { locatorRequired: true, wait: true });
+  if (operation === "browser.fill")
+    return parseTargetInput(candidate, { locatorRequired: true, value: true });
+  if (operation === "browser.select")
+    return parseTargetInput(candidate, { locatorRequired: true, values: true });
+  if (operation === "browser.press")
+    return parseTargetInput(candidate, { locatorRequired: false, key: true });
+  if (operation === "browser.script") {
+    const page = parsePage(candidate.page);
+    const { source, args, timeout } = candidate;
+    return exactKeys(candidate, ["page", "source", "args", "timeout"]) && page !== null && typeof source === "string" && source.length > 0 && source.length <= 1e5 && (args === void 0 || typeof args === "object" && args !== null && !Array.isArray(args)) && (timeout === void 0 || typeof timeout === "number" && timeout >= 0 && timeout <= 12e4) ? {
+      ...page ? { page } : {},
+      source,
+      ...args !== void 0 ? { args } : {},
+      ...typeof timeout === "number" ? { timeout } : {}
+    } : null;
+  }
+  if (operation === "browser.box") return parseTargetInput(candidate, { locatorRequired: true });
+  if (operation === "browser.mouse") {
+    const page = parsePage(candidate.page);
+    const { action, x, y, deltaX, deltaY } = candidate;
+    const point = (value2) => typeof value2 === "number" && Number.isFinite(value2);
+    const needsPoint = action === "move" || action === "click";
+    return exactKeys(candidate, ["page", "action", "x", "y", "deltaX", "deltaY"]) && page !== null && (action === "move" || action === "down" || action === "up" || action === "click") && (!needsPoint || point(x) && point(y)) && deltaX === void 0 && deltaY === void 0 ? { ...page ? { page } : {}, action, ...point(x) ? { x } : {}, ...point(y) ? { y } : {} } : null;
+  }
+  if (operation === "browser.wheel") {
+    const page = parsePage(candidate.page);
+    const { deltaX, deltaY } = candidate;
+    return exactKeys(candidate, ["page", "deltaX", "deltaY"]) && page !== null && (deltaX === void 0 || typeof deltaX === "number") && (deltaY === void 0 || typeof deltaY === "number") ? {
+      ...page ? { page } : {},
+      ...typeof deltaX === "number" ? { deltaX } : {},
+      ...typeof deltaY === "number" ? { deltaY } : {}
+    } : null;
+  }
+  if (operation === "browser.drag") {
+    const page = parsePage(candidate.page);
+    const { from, to, steps } = candidate;
+    const endpoint = (value2) => {
+      if (!value2 || typeof value2 !== "object") return false;
+      const record3 = value2;
+      if (record3.locator !== void 0) return parseBrowserLocator(record3.locator) !== null && exactKeys(record3, ["locator"]);
+      return typeof record3.x === "number" && typeof record3.y === "number" && exactKeys(record3, ["x", "y"]);
+    };
+    return exactKeys(candidate, ["page", "from", "to", "steps"]) && page !== null && endpoint(from) && endpoint(to) && (steps === void 0 || Number.isInteger(steps) && steps >= 1 && steps <= 100) ? { ...page ? { page } : {}, from, to, ...typeof steps === "number" ? { steps } : {} } : null;
+  }
+  if (operation === "browser.scroll") {
+    const page = parsePage(candidate.page);
+    const { direction, amount, expectedRevision } = candidate;
+    return exactKeys(candidate, ["page", "direction", "amount", "expectedRevision"]) && page !== null && (direction === "up" || direction === "down" || direction === "left" || direction === "right") && (amount === void 0 || typeof amount === "number" && amount >= 1 && amount <= 1e4) && (expectedRevision === void 0 || Number.isInteger(expectedRevision) && expectedRevision >= 0) ? {
+      ...page ? { page } : {},
+      direction,
+      ...typeof amount === "number" ? { amount } : {},
+      ...typeof expectedRevision === "number" ? { expectedRevision } : {}
+    } : null;
+  }
+  return parseTargetInput(candidate, { locatorRequired: false });
+}
+function parseBrowserOperationCall(value) {
+  const candidate = record(value);
+  if (!candidate || candidate.protocol !== SUPERCODE_BROWSER_OPERATION_PROTOCOL || typeof candidate.operation !== "string" || !OPERATION_NAMES.has(candidate.operation)) return null;
+  const operation = candidate.operation;
+  const input = parseBrowserOperationInput(operation, candidate.input);
+  return input === null ? null : { protocol: SUPERCODE_BROWSER_OPERATION_PROTOCOL, operation, input };
+}
+function parseBrowserOperationResult(value) {
+  const candidate = record(value);
+  if (!candidate || typeof candidate.ok !== "boolean" || typeof candidate.operation !== "string" || !OPERATION_NAMES.has(candidate.operation)) return null;
+  const operation = candidate.operation;
+  const targetCandidate = record(candidate.target);
+  const target = targetCandidate && (targetCandidate.page === void 0 || typeof targetCandidate.page === "string") && typeof targetCandidate.url === "string" && typeof targetCandidate.title === "string" && Number.isInteger(targetCandidate.revision) ? {
+    ...typeof targetCandidate.page === "string" ? { page: targetCandidate.page } : {},
+    url: targetCandidate.url,
+    title: targetCandidate.title,
+    revision: targetCandidate.revision
+  } : null;
+  if (candidate.ok) return target ? { ok: true, operation, target, value: candidate.value } : null;
+  const error = record(candidate.error);
+  const codes = /* @__PURE__ */ new Set([
+    "APPROVAL_REQUIRED",
+    "INVALID_INPUT",
+    "NOT_AVAILABLE",
+    "NOT_FOUND",
+    "STALE_PAGE",
+    "TIMED_OUT",
+    "UNSUPPORTED",
+    "FAILED"
+  ]);
+  if (!error || typeof error.code !== "string" || !codes.has(error.code) || typeof error.message !== "string") return null;
+  return {
+    ok: false,
+    operation,
+    error: { code: error.code, message: error.message },
+    ...target ? { target } : {}
+  };
+}
+
+// src/executor.ts
+var PLAYWRIGHT_IMPLEMENTATION = "playwright-core 1.63.0";
+var SCRIPT_TIMEOUT_CLAMP_MS = 9e3;
+var ACTION_TIMEOUT_MS = 5e3;
+var WAIT_TIMEOUT_CLAMP_MS = 9e3;
+var PLAYWRIGHT_FEATURES = Object.freeze([
+  "page.ariaSnapshot",
+  "page.keyboard",
+  "page.navigation.history",
+  "locator.css",
+  "locator.ref",
+  "locator.role",
+  "locator.text",
+  "locator.testId",
+  "locator.label",
+  "locator.placeholder",
+  "locator.altText",
+  "locator.title",
+  "locator.first",
+  "locator.nth",
+  "locator.count",
+  "locator.waitFor",
+  "locator.textContent",
+  "locator.inputValue",
+  "locator.getAttribute",
+  "locator.isVisible",
+  "locator.click",
+  "locator.fill",
+  "locator.press",
+  "locator.hover",
+  "locator.focus",
+  "locator.check",
+  "locator.uncheck",
+  "locator.selectOption",
+  "locator.boundingBox",
+  "locator.dragTo",
+  "page.mouse",
+  "page.mouse.wheel",
+  "page.on.console",
+  "page.on.pageerror",
+  "page.consoleMessages",
+  "page.pageErrors",
+  "page.screenshot.png",
+  "page.evaluate"
+]);
+var REVISION_KEY = "__supercodeBrowserRevision";
+function installRevisionCounter(key) {
+  const scope = globalThis;
+  if (typeof scope[key] === "number") return;
+  scope[key] = 0;
+  new MutationObserver(() => {
+    scope[key] = scope[key] + 1;
+  }).observe(document, { attributes: true, childList: true, characterData: true, subtree: true });
+}
+function inspectInPage({ elements, limit }) {
+  const normalize = (value) => value.replace(/\s+/g, " ").trim();
+  const implied = (element) => {
+    const tag = element.tagName.toLowerCase();
+    if (tag === "button") return "button";
+    if (tag === "a" && element.hasAttribute("href")) return "link";
+    if (/^h[1-6]$/.test(tag)) return "heading";
+    if (tag === "textarea") return "textbox";
+    if (tag === "select") return "combobox";
+    if (tag === "option") return "option";
+    if (tag === "img") return "img";
+    if (tag === "ul" || tag === "ol") return "list";
+    if (tag === "li") return "listitem";
+    if (tag === "nav") return "navigation";
+    if (tag === "main") return "main";
+    if (tag === "form") return "form";
+    if (tag === "input") {
+      const type = (element.getAttribute("type") ?? "text").toLowerCase();
+      if (type === "button" || type === "submit" || type === "reset") return "button";
+      if (type === "checkbox") return "checkbox";
+      if (type === "radio") return "radio";
+      if (type === "range") return "slider";
+      return "textbox";
+    }
+    return null;
+  };
+  const nameOf = (element) => {
+    const aria = element.getAttribute("aria-label");
+    if (aria?.trim()) return normalize(aria);
+    const ids = element.getAttribute("aria-labelledby")?.split(/\s+/).filter(Boolean) ?? [];
+    const labelled = normalize(ids.map((id) => element.ownerDocument.getElementById(id)?.textContent ?? "").join(" "));
+    if (labelled) return labelled;
+    if (element instanceof HTMLInputElement && element.labels?.length) {
+      const label = normalize(Array.from(element.labels).map((candidate) => candidate.textContent ?? "").join(" "));
+      if (label) return label;
+    }
+    for (const attribute of ["alt", "title", "placeholder"]) {
+      const value = element.getAttribute(attribute);
+      if (value?.trim()) return normalize(value);
+    }
+    return normalize(element.textContent ?? "");
+  };
+  const visible = (element) => {
+    if (element.getAttribute("aria-hidden") === "true") return false;
+    if (!(element instanceof HTMLElement)) return true;
+    if (element.hidden) return false;
+    const style = getComputedStyle(element);
+    return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+  };
+  return elements.slice(0, limit).map((element) => {
+    const role = element.getAttribute("role")?.trim() || implied(element);
+    const name = nameOf(element).slice(0, 500);
+    const value = element instanceof HTMLInputElement ? element.type === "password" ? "<redacted>" : element.value : element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement ? element.value : void 0;
+    const checked = element instanceof HTMLInputElement && (element.type === "checkbox" || element.type === "radio") ? element.checked : void 0;
+    return {
+      tag: element.tagName.toLowerCase(),
+      ...role ? { role } : {},
+      ...name ? { name } : {},
+      ...value !== void 0 ? { value: value.slice(0, 2e3) } : {},
+      disabled: (element instanceof HTMLButtonElement || element instanceof HTMLInputElement || element instanceof HTMLSelectElement) && element.disabled,
+      ...checked !== void 0 ? { checked } : {},
+      visible: visible(element)
+    };
+  });
+}
+function scrollInPage(delta) {
+  const amount = delta.amount ?? Math.max(240, Math.round(window.innerHeight * 0.8));
+  window.scrollBy({ left: delta.left * amount, top: delta.top * amount, behavior: "instant" });
+  return { x: window.scrollX, y: window.scrollY };
+}
+function pngSize(bytes) {
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (bytes.length < 24 || !signature.every((byte, index) => bytes[index] === byte)) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+function base64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 32768)
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+  return btoa(binary);
+}
+function serializableValue(value, syntheticEvents) {
+  if (value === void 0) return null;
+  const replacer = (_key, item) => {
+    const bytes = item instanceof Uint8Array ? item : item && typeof item === "object" && item.type === "Buffer" && Array.isArray(item.data) ? Uint8Array.from(item.data) : null;
+    if (!bytes) return item;
+    const size = pngSize(bytes);
+    const encoded = base64(bytes);
+    if (!size) return encoded;
+    const dataUrl = `data:image/png;base64,${encoded}`;
+    if (dataUrl.length > 768 * 1024) return { error: "Screenshot exceeds the 768 KiB image record bound.", width: size.width, height: size.height };
+    return {
+      dataUrl,
+      format: "png",
+      width: size.width,
+      height: size.height,
+      fidelity: syntheticEvents ? "Pixels rasterized by the CDP endpoint's own renderer." : "Native Chrome pixels captured over CDP."
+    };
+  };
+  try {
+    return JSON.parse(JSON.stringify(value, replacer));
+  } catch {
+    return String(value);
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function classifyPlaywrightError(error) {
+  if (error instanceof BrowserActionRefusal) return error.code;
+  if (error instanceof errors.TimeoutError) return "TIMED_OUT";
+  const message = errorMessage(error);
+  if (/has been closed|Target closed|Target page, context or browser|Browser closed|browser has disconnected|Session closed|detached/i.test(message))
+    return "NOT_AVAILABLE";
+  if (/strict mode violation|resolved to 0 elements|no element matches|matched no element/i.test(message))
+    return "NOT_FOUND";
+  if (/unavailable|not supported/i.test(message)) return "UNSUPPORTED";
+  return "FAILED";
+}
+var PlaywrightOperationExecutor = class {
+  page;
+  options;
+  ready;
+  constructor(page, options) {
+    this.page = page;
+    this.options = options;
+    this.ready = (async () => {
+      await page.addInitScript(installRevisionCounter, REVISION_KEY);
+      await page.evaluate(installRevisionCounter, REVISION_KEY).catch(() => void 0);
+    })();
+  }
+  async execute(raw) {
+    const call = parseBrowserOperationCall(raw);
+    const operation = operationName(raw);
+    if (!call) return this.failure(operation, "INVALID_INPUT", "Invalid browser operation request.");
+    try {
+      await this.ready;
+      return await this.executeCall(call);
+    } catch (error) {
+      return this.failure(call.operation, classifyPlaywrightError(error), errorMessage(error));
+    }
+  }
+  locator(value, index) {
+    const locator = value;
+    const exact = (candidate) => candidate.exact !== void 0 ? { exact: candidate.exact } : {};
+    const page = this.page;
+    const base = locator.by === "css" ? page.locator(locator.value) : locator.by === "ref" ? page.locator(`aria-ref=${locator.value}`) : locator.by === "role" ? page.getByRole(locator.role, {
+      ...locator.name !== void 0 ? { name: locator.name } : {},
+      // A role's name matches exactly unless told otherwise.
+      exact: locator.exact ?? true
+    }) : locator.by === "text" ? page.getByText(locator.text, exact(locator)) : locator.by === "label" ? page.getByLabel(locator.text, exact(locator)) : locator.by === "placeholder" ? page.getByPlaceholder(locator.text, exact(locator)) : locator.by === "altText" ? page.getByAltText(locator.text, exact(locator)) : locator.by === "title" ? page.getByTitle(locator.text, exact(locator)) : page.getByTestId(locator.value);
+    return index === void 0 ? base : index === 0 ? base.first() : base.nth(index);
+  }
+  /**
+   * Playwright's `aria-ref` engine resolves against the last AI-mode snapshot
+   * the page took. Refs are stable per element, so refreshing the whole-page
+   * snapshot before resolving one keeps every ref from `browser.snapshot`
+   * addressable even after an element-scoped snapshot replaced the map.
+   */
+  async refreshRefs(value) {
+    if (value?.by === "ref")
+      await this.page.ariaSnapshot({ mode: "ai", timeout: ACTION_TIMEOUT_MS });
+  }
+  async refOf(locator) {
+    try {
+      const nodes = await locator.ariaSnapshotJSON({ mode: "ai", depth: 1, timeout: ACTION_TIMEOUT_MS });
+      const first = Array.isArray(nodes) ? nodes.find((node) => node && typeof node === "object") : void 0;
+      return typeof first?.ref === "string" ? first.ref : "";
+    } catch {
+      return "";
+    }
+  }
+  async inspectAll(locator, limit) {
+    const handles = (await locator.elementHandles()).slice(0, limit);
+    let fields;
+    try {
+      const inspect = inspectInPage;
+      fields = await this.page.evaluate(inspect, { elements: handles, limit });
+    } finally {
+      await Promise.all(handles.map((handle) => handle.dispose().catch(() => void 0)));
+    }
+    const refs = await Promise.all(fields.map((_, index) => this.refOf(locator.nth(index))));
+    return fields.map((field, index) => ({ ref: refs[index] ?? "", ...field }));
+  }
+  async inspect(locator) {
+    const [inspection] = await this.inspectAll(locator.first(), 1);
+    if (!inspection) throw new BrowserActionRefusal("NOT_FOUND", "The locator matched no element.");
+    return inspection;
+  }
+  /** Run a locator action; a failure on a locator that matches nothing is NOT_FOUND. */
+  async act(locator, action, run) {
+    try {
+      return await run();
+    } catch (error) {
+      if (!(error instanceof BrowserActionRefusal) && await locator.count().catch(() => 1) === 0)
+        throw new BrowserActionRefusal("NOT_FOUND", `${action} found no element for the locator.`);
+      throw error;
+    }
+  }
+  /** The host's policy for an action; an element that is not there is the action's own failure. */
+  async guard(action) {
+    if (!this.options.actionGuard || await action.locator.count().catch(() => 0) === 0) return;
+    await this.options.actionGuard(action);
+  }
+  async revision() {
+    const value = await this.page.evaluate((key) => globalThis[key], REVISION_KEY).catch(() => void 0);
+    return typeof value === "number" ? value : 0;
+  }
+  async executeCall(call) {
+    const input = call.input;
+    const page = this.page;
+    const expectedRevision = typeof input.expectedRevision === "number" ? input.expectedRevision : void 0;
+    if (expectedRevision !== void 0) {
+      const current = await this.revision();
+      if (expectedRevision !== current)
+        return this.failure(call.operation, "STALE_PAGE", `The page changed (expected revision ${expectedRevision}, current revision ${current}).`);
+    }
+    if (call.operation === "browser.status")
+      return this.success(call.operation, {
+        available: true,
+        features: PLAYWRIGHT_FEATURES,
+        syntheticEvents: this.options.syntheticEvents,
+        implementation: PLAYWRIGHT_IMPLEMENTATION,
+        endpoint: this.options.endpoint
+      });
+    if (call.operation === "browser.snapshot") {
+      await this.refreshRefs(input.locator);
+      const scoped = input.locator ? this.locator(input.locator).first() : null;
+      const text = scoped ? await this.act(scoped, "ariaSnapshot", () => scoped.ariaSnapshot({ mode: "ai", timeout: ACTION_TIMEOUT_MS })) : await page.ariaSnapshot({ mode: "ai", timeout: ACTION_TIMEOUT_MS });
+      const bounded = text.slice(0, 64e3);
+      return this.success(call.operation, { text: bounded, truncated: bounded.length < text.length });
+    }
+    if (call.operation === "browser.query") {
+      await this.refreshRefs(input.locator);
+      const locator2 = this.locator(input.locator, typeof input.index === "number" ? input.index : void 0);
+      const count = await locator2.count();
+      return this.success(call.operation, { count, matches: await this.inspectAll(locator2, 50), truncated: count > 50 });
+    }
+    if (call.operation === "browser.wait") {
+      await this.refreshRefs(input.locator);
+      const requested = typeof input.timeout === "number" ? input.timeout : 5e3;
+      const timeout2 = Math.min(requested, WAIT_TIMEOUT_CLAMP_MS);
+      const locator2 = this.locator(input.locator, typeof input.index === "number" ? input.index : 0);
+      try {
+        await locator2.waitFor({ state: input.state === "attached" ? "attached" : "visible", timeout: timeout2 });
+      } catch (error) {
+        if (error instanceof errors.TimeoutError)
+          throw new BrowserActionRefusal("TIMED_OUT", `waitFor timed out after ${timeout2}ms` + (timeout2 < requested ? ` (the requested ${requested}ms is clamped to ${WAIT_TIMEOUT_CLAMP_MS}ms by the provider call deadline)` : "") + ".");
+        throw error;
+      }
+      return this.success(call.operation, { ready: true });
+    }
+    if (call.operation === "browser.scroll") {
+      const direction = input.direction;
+      const position = await page.evaluate(scrollInPage, {
+        left: direction === "left" ? -1 : direction === "right" ? 1 : 0,
+        top: direction === "up" ? -1 : direction === "down" ? 1 : 0,
+        amount: typeof input.amount === "number" ? input.amount : null
+      });
+      return this.success(call.operation, position);
+    }
+    if (call.operation === "browser.script") return this.script(call);
+    if (call.operation === "browser.mouse") {
+      const action = input.action;
+      if (action === "move") await page.mouse.move(input.x, input.y);
+      else if (action === "click") await page.mouse.click(input.x, input.y);
+      else if (action === "down") await page.mouse.down();
+      else await page.mouse.up();
+      return this.success(call.operation, { action, ...typeof input.x === "number" ? { x: input.x, y: input.y } : {} });
+    }
+    if (call.operation === "browser.wheel") {
+      const deltaX = typeof input.deltaX === "number" ? input.deltaX : 0;
+      const deltaY = typeof input.deltaY === "number" ? input.deltaY : 0;
+      await page.mouse.wheel(deltaX, deltaY);
+      return this.success(call.operation, { deltaX, deltaY });
+    }
+    if (call.operation === "browser.drag") {
+      const resolve = async (endpoint) => {
+        if (endpoint.locator === void 0) return { x: endpoint.x, y: endpoint.y };
+        await this.refreshRefs(endpoint.locator);
+        const locator2 = this.locator(endpoint.locator).first();
+        const box = await locator2.count() === 0 ? null : await locator2.boundingBox({ timeout: ACTION_TIMEOUT_MS });
+        if (!box) throw new BrowserActionRefusal("NOT_FOUND", "The drag locator matched no element.");
+        return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+      };
+      for (const end of [input.from, input.to])
+        if (end.locator !== void 0) await this.guard({ action: "drag", locator: this.locator(end.locator).first() });
+      const from = await resolve(input.from);
+      const to = await resolve(input.to);
+      await page.mouse.move(from.x, from.y);
+      await page.mouse.down();
+      await page.mouse.move(to.x, to.y, { steps: typeof input.steps === "number" ? input.steps : 8 });
+      await page.mouse.up();
+      return this.success(call.operation, { from, to });
+    }
+    if (call.operation === "browser.back") {
+      await page.goBack({ waitUntil: "commit", timeout: ACTION_TIMEOUT_MS });
+      return this.success(call.operation, { requested: true });
+    }
+    if (call.operation === "browser.forward") {
+      await page.goForward({ waitUntil: "commit", timeout: ACTION_TIMEOUT_MS });
+      return this.success(call.operation, { requested: true });
+    }
+    if (call.operation === "browser.reload") {
+      await page.reload({ waitUntil: "commit", timeout: ACTION_TIMEOUT_MS });
+      return this.success(call.operation, { requested: true });
+    }
+    await this.refreshRefs(input.locator);
+    const locator = input.locator ? this.locator(input.locator, typeof input.index === "number" ? input.index : 0) : null;
+    const timeout = ACTION_TIMEOUT_MS;
+    if (call.operation === "browser.box") {
+      const box = await locator.count() === 0 ? null : await locator.boundingBox({ timeout });
+      if (!box) return this.failure(call.operation, "NOT_FOUND", "The locator matched no element.");
+      return this.success(call.operation, box);
+    }
+    if (call.operation === "browser.press" && !locator) {
+      await this.guard({ action: "press", locator: page.locator("*:focus").first(), value: input.key });
+      await page.keyboard.press(input.key);
+      return this.success(call.operation, { key: input.key });
+    }
+    const target = locator;
+    const guarded = call.operation === "browser.select" ? "select" : call.operation.slice("browser.".length);
+    await this.guard({
+      action: guarded,
+      locator: target.first(),
+      ...call.operation === "browser.fill" ? { value: input.value } : call.operation === "browser.press" ? { value: input.key } : call.operation === "browser.select" ? { value: input.values } : {}
+    });
+    const before = await this.inspect(target).catch(() => null);
+    if (call.operation === "browser.click") await this.act(target, "click", () => target.click({ timeout }));
+    else if (call.operation === "browser.fill") await this.act(target, "fill", () => target.fill(input.value, { timeout }));
+    else if (call.operation === "browser.press") await this.act(target, "press", () => target.press(input.key, { timeout }));
+    else if (call.operation === "browser.hover") await this.act(target, "hover", () => target.hover({ timeout }));
+    else if (call.operation === "browser.focus") await this.act(target, "focus", () => target.focus({ timeout }));
+    else if (call.operation === "browser.check") await this.act(target, "check", () => target.check({ timeout }));
+    else if (call.operation === "browser.uncheck") await this.act(target, "uncheck", () => target.uncheck({ timeout }));
+    else if (call.operation === "browser.select") {
+      const values = await this.act(target, "selectOption", () => target.selectOption(input.values, { timeout }));
+      return this.success(call.operation, { values });
+    }
+    const after = await this.inspect(target).catch(() => null);
+    const inspection = after ?? before;
+    if (!inspection) throw new BrowserActionRefusal("NOT_FOUND", "The locator matched no element.");
+    return this.success(call.operation, inspection);
+  }
+  async script(call) {
+    const input = call.input;
+    const source = input.source;
+    const args = input.args ?? {};
+    const requested = typeof input.timeout === "number" ? input.timeout : 3e4;
+    const timeout = Math.min(requested, SCRIPT_TIMEOUT_CLAMP_MS);
+    const AsyncFunction = Object.getPrototypeOf(async function() {
+    }).constructor;
+    let run;
+    try {
+      run = new AsyncFunction("page", "args", source);
+    } catch (error) {
+      return this.failure(call.operation, "FAILED", `The script did not parse: ${errorMessage(error)}`);
+    }
+    const notice = timeout < requested ? `The script timeout is clamped to ${SCRIPT_TIMEOUT_CLAMP_MS}ms: the harness abandons a provider call at 12 s.` : void 0;
+    let timer;
+    try {
+      const value = await Promise.race([
+        run(this.page, args),
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(() => reject(new BrowserActionRefusal("FAILED", `The script exceeded ${timeout}ms.` + (notice ? ` ${notice}` : ""))), timeout);
+        })
+      ]);
+      return this.success(call.operation, {
+        value: serializableValue(value, this.options.syntheticEvents),
+        ...notice ? { notice } : {}
+      });
+    } finally {
+      clearTimeout(timer);
+      this.page.removeAllListeners();
+    }
+  }
+  async target() {
+    if (this.page.isClosed()) return { url: "", title: "", revision: 0 };
+    const bounded = (promise, fallback) => {
+      let timer;
+      return Promise.race([
+        promise.catch(() => fallback),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(fallback), 1e3);
+        })
+      ]).finally(() => clearTimeout(timer));
+    };
+    const [title, revision] = await Promise.all([
+      bounded(this.page.title(), ""),
+      bounded(this.revision(), 0)
+    ]);
+    return { url: this.page.url(), title, revision };
+  }
+  async success(operation, value) {
+    return { ok: true, operation, target: await this.target(), value };
+  }
+  async failure(operation, code, message) {
+    return { ok: false, operation, error: { code, message }, target: await this.target() };
+  }
+};
+function operationName(raw) {
+  const candidate = raw && typeof raw === "object" && !Array.isArray(raw) ? raw.operation : void 0;
+  return typeof candidate === "string" && BROWSER_OPERATION_NAMES.includes(candidate) ? candidate : "browser.status";
+}
+
+// src/provider.ts
+import { timingSafeEqual } from "node:crypto";
+import { chromium } from "playwright-core";
+var MAX_REQUEST_BYTES = 256 * 1024;
+var MAX_RESPONSE_BYTES = 1024 * 1024;
+function record2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function tokenMatches(expected, actual) {
+  if (typeof actual !== "string") return false;
+  const left = Buffer.from(expected);
+  const right = Buffer.from(actual);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+function callOperation(call) {
+  const operation = record2(call)?.operation;
+  return typeof operation === "string" && operation.startsWith("browser.") ? operation : "browser.status";
+}
+function createPlaywrightBrowserProvider(options) {
+  if (!/^[0-9a-f]{32,}$/i.test(options.token))
+    throw new Error("The provider token must be at least 32 hexadecimal characters.");
+  let connection = null;
+  let queue = Promise.resolve();
+  const usable = (candidate) => candidate !== null && candidate.browser.isConnected() && !candidate.page.isClosed();
+  const connect = async () => {
+    const previous = connection;
+    connection = null;
+    const browser = previous?.browser.isConnected() ? previous.browser : await chromium.connectOverCDP(options.cdpUrl, { noDefaults: true });
+    const page = browser.contexts()[0]?.pages()[0];
+    if (!page) {
+      if (browser !== previous?.browser) await browser.close().catch(() => void 0);
+      throw new Error("The browser has no open page.");
+    }
+    const executor = new PlaywrightOperationExecutor(page, {
+      syntheticEvents: options.syntheticEvents,
+      endpoint: browser.version()
+    });
+    connection = { browser, page, executor };
+    return connection;
+  };
+  const failure = (operation, code, message) => ({ ok: false, operation, error: { code, message } });
+  const run = async (call) => {
+    let current = connection;
+    if (!usable(current)) {
+      try {
+        current = await connect();
+      } catch (error) {
+        return failure(
+          callOperation(call),
+          "NOT_AVAILABLE",
+          `The CDP endpoint is not available: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    return current.executor.execute(call);
+  };
+  return {
+    token: options.token,
+    async handle(request) {
+      const envelope = record2(request);
+      const id = typeof envelope?.id === "string" && envelope.id.length > 0 && envelope.id.length <= 256 ? envelope.id : null;
+      const respond = (result2) => ({ protocol: SUPERCODE_BROWSER_PROVIDER_PROTOCOL, id, result: result2 });
+      const call = envelope?.call;
+      const operation = callOperation(call);
+      if (!envelope || envelope.protocol !== SUPERCODE_BROWSER_PROVIDER_PROTOCOL || id === null || record2(call)?.protocol !== SUPERCODE_BROWSER_OPERATION_PROTOCOL)
+        return respond(failure(operation, "INVALID_INPUT", "Invalid browser provider request envelope."));
+      if (!tokenMatches(options.token, envelope.token))
+        return respond(failure(operation, "INVALID_INPUT", "Invalid browser provider token."));
+      const result = queue.then(() => run(call));
+      queue = result.catch(() => void 0);
+      return respond(await result);
+    },
+    async close() {
+      const current = connection;
+      connection = null;
+      await current?.browser.close().catch(() => void 0);
+    }
+  };
+}
+
+// src/serve.ts
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+var HOST = "127.0.0.1";
+function defaultProvidersDirectory() {
+  const env = process.env;
+  const root = env.SUPERCODE_HOME ? env.SUPERCODE_HOME : env.XDG_CONFIG_HOME ? path.join(env.XDG_CONFIG_HOME, "supercode") : env.HOME ? path.join(env.HOME, ".config", "supercode") : path.join(os.tmpdir(), "supercode");
+  return path.join(root, "providers");
+}
+function invalid(id, message) {
+  return {
+    protocol: SUPERCODE_BROWSER_PROVIDER_PROTOCOL,
+    id,
+    result: { ok: false, operation: "browser.status", error: { code: "INVALID_INPUT", message } }
+  };
+}
+function encode(response) {
+  const text = JSON.stringify(response);
+  if (Buffer.byteLength(text) <= MAX_RESPONSE_BYTES) return text;
+  return JSON.stringify({
+    ...response,
+    result: {
+      ok: false,
+      operation: response.result.operation,
+      error: { code: "FAILED", message: "The operation result exceeds the provider's 1 MiB response bound." }
+    }
+  });
+}
+async function answer(provider, body) {
+  let request;
+  try {
+    request = JSON.parse(body);
+  } catch {
+    return invalid(null, "The request is not JSON.");
+  }
+  return provider.handle(request);
+}
+async function serveTcp(provider, options) {
+  const server = net.createServer((socket) => {
+    const chunks = [];
+    let size = 0;
+    let done = false;
+    const finish = (response) => {
+      if (socket.destroyed) return;
+      socket.end(`${encode(response)}
+`);
+    };
+    socket.setTimeout(15e3, () => socket.destroy());
+    socket.on("error", () => socket.destroy());
+    socket.on("data", (chunk) => {
+      if (done) return;
+      const newline = chunk.indexOf(10);
+      const part = newline === -1 ? chunk : chunk.subarray(0, newline);
+      size += part.length + (newline === -1 ? 0 : 1);
+      if (size > MAX_REQUEST_BYTES) {
+        done = true;
+        finish(invalid(null, "The request exceeds 256 KiB."));
+        return;
+      }
+      chunks.push(part);
+      if (newline === -1) return;
+      done = true;
+      void answer(provider, Buffer.concat(chunks).toString("utf8")).then(finish, (error) => finish(invalid(null, error instanceof Error ? error.message : String(error))));
+    });
+    socket.on("end", () => {
+      if (done) return;
+      done = true;
+      void answer(provider, Buffer.concat(chunks).toString("utf8")).then(finish, () => socket.destroy());
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, HOST, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const port2 = server.address().port;
+  const directory = path.join(options.providersDirectory ?? defaultProvidersDirectory(), "browser");
+  fs.mkdirSync(directory, { recursive: true, mode: 448 });
+  fs.chmodSync(directory, 448);
+  const id = `playwright.cdp.${port2}`;
+  const discoveryPath = path.join(directory, `${id}.json`);
+  const workspace = fs.realpathSync(options.workspace ?? process.cwd());
+  const discovery = {
+    protocol: SUPERCODE_BROWSER_PROVIDER_PROTOCOL,
+    workspace,
+    host: HOST,
+    port: port2,
+    token: provider.token,
+    provider: {
+      id,
+      name: "Playwright over CDP",
+      fidelity: {
+        implementation: PLAYWRIGHT_IMPLEMENTATION,
+        transport: "cdp",
+        accessibility: "playwright-aria-snapshot",
+        syntheticEvents: options.syntheticEvents,
+        trustedInput: !options.syntheticEvents,
+        script: "node-playwright-page"
+      }
+    }
+  };
+  const temporary = `${discoveryPath}.${randomBytes(6).toString("hex")}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(discovery, null, 2)}
+`, { mode: 384, flag: "wx" });
+  fs.renameSync(temporary, discoveryPath);
+  return {
+    framing: "tcp",
+    port: port2,
+    discoveryPath,
+    async stop() {
+      fs.rmSync(discoveryPath, { force: true });
+      await new Promise((resolve) => server.close(() => resolve()));
+    }
+  };
+}
+async function serveHttp(provider, options) {
+  const server = http.createServer((request, response) => {
+    const send = (status, body) => {
+      response.writeHead(status, body === void 0 ? {} : { "content-type": "application/json" });
+      response.end(body);
+    };
+    const pathname = (request.url ?? "/").split("?", 1)[0];
+    if (pathname !== "/") {
+      request.resume();
+      send(404);
+      return;
+    }
+    if (request.method !== "POST") {
+      request.resume();
+      response.setHeader("allow", "POST");
+      send(405);
+      return;
+    }
+    const chunks = [];
+    let size = 0;
+    let rejected = false;
+    request.on("data", (chunk) => {
+      if (rejected) return;
+      size += chunk.length;
+      if (size > MAX_REQUEST_BYTES) {
+        rejected = true;
+        send(413, encode(invalid(null, "The request exceeds 256 KiB.")));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on("end", () => {
+      if (rejected) return;
+      let body;
+      try {
+        body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      } catch {
+        send(400, encode(invalid(null, "The request is not JSON.")));
+        return;
+      }
+      void provider.handle(body).then(
+        (result) => send(200, encode(result)),
+        (error) => send(500, encode(invalid(null, error instanceof Error ? error.message : String(error))))
+      );
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, HOST, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const port2 = server.address().port;
+  return {
+    framing: "http",
+    port: port2,
+    async stop() {
+      await new Promise((resolve) => server.close(() => resolve()));
+    }
+  };
+}
+
+// src/cli.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
+import { parseArgs } from "node:util";
+var USAGE = "usage: supercode-browser-playwright --cdp-url <url> (--tcp <port> [--providers-dir <dir>] [--workspace <path>] | --http <port>) [--token <hex>] [--synthetic-events]";
+function port(value, flag) {
+  const parsed = Number(value);
+  if (!/^\d+$/.test(value) || parsed > 65535) throw new Error(`${flag} must be a port number (0 picks a free one).`);
+  return parsed;
+}
+async function main(argv) {
+  const { values } = parseArgs({
+    args: [...argv],
+    strict: true,
+    allowPositionals: false,
+    options: {
+      "cdp-url": { type: "string" },
+      tcp: { type: "string" },
+      http: { type: "string" },
+      "providers-dir": { type: "string" },
+      workspace: { type: "string" },
+      token: { type: "string" },
+      "synthetic-events": { type: "boolean", default: false }
+    }
+  });
+  const cdpUrl = values["cdp-url"];
+  if (!cdpUrl) throw new Error(`--cdp-url is required.
+${USAGE}`);
+  if (values.tcp === void 0 === (values.http === void 0))
+    throw new Error(`Exactly one of --tcp and --http is required.
+${USAGE}`);
+  if (values.http !== void 0 && (values["providers-dir"] !== void 0 || values.workspace !== void 0))
+    throw new Error(`--providers-dir and --workspace belong to the TCP framing.
+${USAGE}`);
+  if (values.http !== void 0 && values.token === void 0)
+    throw new Error("--http requires --token: the host that calls the provider passes it.");
+  const token = values.token ?? randomBytes2(32).toString("hex");
+  const syntheticEvents = values["synthetic-events"] ?? false;
+  const provider = createPlaywrightBrowserProvider({ cdpUrl, token, syntheticEvents });
+  const handle = values.tcp !== void 0 ? await serveTcp(provider, {
+    port: port(values.tcp, "--tcp"),
+    syntheticEvents,
+    ...values["providers-dir"] !== void 0 ? { providersDirectory: values["providers-dir"] } : {},
+    ...values.workspace !== void 0 ? { workspace: values.workspace } : {}
+  }) : await serveHttp(provider, { port: port(values.http, "--http") });
+  process.stdout.write(`${JSON.stringify({ listening: { framing: handle.framing, port: handle.port } })}
+`);
+  let stopping = false;
+  const stop = () => {
+    if (stopping) return;
+    stopping = true;
+    void Promise.allSettled([handle.stop(), provider.close()]).then(() => process.exit(0));
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  process.once("SIGHUP", stop);
+  return handle;
+}
+export {
+  ACTION_TIMEOUT_MS,
+  BROWSER_OPERATION_NAMES,
+  BrowserActionRefusal,
+  MAX_REQUEST_BYTES,
+  MAX_RESPONSE_BYTES,
+  PLAYWRIGHT_FEATURES,
+  PLAYWRIGHT_IMPLEMENTATION,
+  PlaywrightOperationExecutor,
+  SCRIPT_TIMEOUT_CLAMP_MS,
+  SUPERCODE_BROWSER_OPERATION_PROTOCOL,
+  SUPERCODE_BROWSER_PROVIDER_PROTOCOL,
+  WAIT_TIMEOUT_CLAMP_MS,
+  classifyPlaywrightError,
+  createPlaywrightBrowserProvider,
+  defaultProvidersDirectory,
+  main,
+  parseBrowserLocator,
+  parseBrowserOperationCall,
+  parseBrowserOperationResult,
+  serveHttp,
+  serveTcp
+};
+//# sourceMappingURL=index.mjs.map