agentic-browser 2.0.1 → 2.2.0

package/dist/{runtime-DUSoQl5x.mjs → runtime-CRkUsvhV.mjs}

@@ -5,10 +5,9 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import WebSocket, { WebSocketServer } from "ws";
-import { URL as URL$1, fileURLToPath } from "node:url";
 import crypto from "node:crypto";
+import { URL as URL$1 } from "node:url";
 import { z } from "zod";
-
 //#region src/session/chrome-launcher.ts
 const CANDIDATES = [
 	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
@@ -22,33 +21,93 @@ function discoverChrome(explicitPath) {
 	if (!found) throw new Error("No supported Chrome installation found.");
 	return found;
 }
-
-//#endregion
-//#region src/session/extension-loader.ts
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-function loadControlExtension() {
-	const packageRoot = path.resolve(__dirname, "..");
-	return {
-		extensionPath: path.resolve(packageRoot, "extension"),
-		loadedAt: (/* @__PURE__ */ new Date()).toISOString()
-	};
-}
-
 //#endregion
 //#region src/session/browser-controller.ts
 var CdpConnection = class CdpConnection {
 	nextId = 0;
+	pendingRequests = /* @__PURE__ */ new Map();
+	pendingEvents = /* @__PURE__ */ new Map();
+	eventHandlers = /* @__PURE__ */ new Map();
+	closed = false;
 	constructor(ws) {
 		this.ws = ws;
+		this.ensureListening();
 	}
 	static async connect(targetWsUrl) {
 		const ws = new WebSocket(targetWsUrl);
 		await new Promise((resolve, reject) => {
-			ws.once("open", () => resolve());
-			ws.once("error", (err) => reject(err));
+			const onOpen = () => {
+				ws.off("error", onError);
+				resolve();
+			};
+			const onError = (err) => {
+				ws.off("open", onOpen);
+				reject(err);
+			};
+			ws.once("open", onOpen);
+			ws.once("error", onError);
 		});
 		return new CdpConnection(ws);
 	}
+	ensureListening() {
+		this.ws.on("message", this.handleMessage);
+		this.ws.once("close", this.handleClose);
+		this.ws.on("error", this.handleError);
+	}
+	handleMessage = (raw) => {
+		let message;
+		try {
+			message = JSON.parse(raw.toString("utf8"));
+		} catch {
+			return;
+		}
+		if (typeof message.id === "number") {
+			const pending = this.pendingRequests.get(message.id);
+			if (!pending) return;
+			this.pendingRequests.delete(message.id);
+			clearTimeout(pending.timeout);
+			if (message.error) {
+				pending.reject(new Error(message.error.message));
+				return;
+			}
+			pending.resolve(message.result ?? {});
+			return;
+		}
+		if (!message.method) return;
+		const params = message.params ?? {};
+		const handlers = this.eventHandlers.get(message.method);
+		if (handlers) for (const handler of handlers) handler(params);
+		const waiters = this.pendingEvents.get(message.method);
+		if (!waiters?.length) return;
+		this.pendingEvents.delete(message.method);
+		for (const waiter of waiters) {
+			clearTimeout(waiter.timeout);
+			waiter.resolve(params);
+		}
+	};
+	handleError = (err) => {
+		this.failAllPending(err);
+	};
+	handleClose = () => {
+		this.failAllPending(/* @__PURE__ */ new Error("CDP connection closed"));
+	};
+	failAllPending(error) {
+		if (this.closed) return;
+		this.closed = true;
+		this.ws.off("message", this.handleMessage);
+		this.ws.off("error", this.handleError);
+		for (const pending of this.pendingRequests.values()) {
+			clearTimeout(pending.timeout);
+			pending.reject(error);
+		}
+		this.pendingRequests.clear();
+		for (const waiters of this.pendingEvents.values()) for (const waiter of waiters) {
+			clearTimeout(waiter.timeout);
+			waiter.reject(error);
+		}
+		this.pendingEvents.clear();
+		this.eventHandlers.clear();
+	}
 	async send(method, params, timeoutMs = 15e3) {
 		if (this.ws.readyState !== WebSocket.OPEN) throw new Error(`WebSocket not open (state=${this.ws.readyState}), cannot send '${method}'`);
 		const id = ++this.nextId;
@@ -59,51 +118,55 @@ var CdpConnection = class CdpConnection {
 		};
 		return await new Promise((resolve, reject) => {
 			const timeout = setTimeout(() => {
-				this.ws.off("message", onMessage);
+				this.pendingRequests.delete(id);
 				reject(/* @__PURE__ */ new Error(`CDP call '${method}' timed out after ${timeoutMs}ms`));
 			}, timeoutMs);
-			const onMessage = (raw) => {
-				const message = JSON.parse(raw.toString("utf8"));
-				if (message.id !== id) return;
-				clearTimeout(timeout);
-				this.ws.off("message", onMessage);
-				if (message.error) {
-					reject(new Error(message.error.message));
-					return;
-				}
-				resolve(message.result ?? {});
-			};
-			this.ws.on("message", onMessage);
+			this.pendingRequests.set(id, {
+				resolve: (value) => resolve(value),
+				reject,
+				timeout
+			});
 			this.ws.send(JSON.stringify(payload));
 		});
 	}
 	waitForEvent(method, timeoutMs = 5e3) {
 		return new Promise((resolve, reject) => {
 			const timeout = setTimeout(() => {
-				this.ws.off("message", onMessage);
+				const waiters = this.pendingEvents.get(method);
+				if (!waiters) {
+					reject(/* @__PURE__ */ new Error(`Timed out waiting for ${method}`));
+					return;
+				}
+				const next = waiters.filter((waiter) => waiter.timeout !== timeout);
+				if (next.length > 0) this.pendingEvents.set(method, next);
+				else this.pendingEvents.delete(method);
 				reject(/* @__PURE__ */ new Error(`Timed out waiting for ${method}`));
 			}, timeoutMs);
-			const onMessage = (raw) => {
-				const message = JSON.parse(raw.toString("utf8"));
-				if (message.method !== method) return;
-				clearTimeout(timeout);
-				this.ws.off("message", onMessage);
-				resolve(message.params ?? {});
-			};
-			this.ws.on("message", onMessage);
+			const waiters = this.pendingEvents.get(method) ?? [];
+			waiters.push({
+				resolve: (value) => resolve(value),
+				reject,
+				timeout
+			});
+			this.pendingEvents.set(method, waiters);
 		});
 	}
 	onEvent(method, handler) {
-		const onMessage = (raw) => {
-			const message = JSON.parse(raw.toString("utf8"));
-			if (message.method === method) handler(message.params ?? {});
+		const handlers = this.eventHandlers.get(method) ?? /* @__PURE__ */ new Set();
+		const wrapped = (params) => {
+			handler(params);
 		};
-		this.ws.on("message", onMessage);
+		handlers.add(wrapped);
+		this.eventHandlers.set(method, handlers);
 		return () => {
-			this.ws.off("message", onMessage);
+			const current = this.eventHandlers.get(method);
+			if (!current) return;
+			current.delete(wrapped);
+			if (current.size === 0) this.eventHandlers.delete(method);
 		};
 	}
 	close() {
+		this.failAllPending(/* @__PURE__ */ new Error("CDP connection closed"));
 		this.ws.close();
 	}
 };
@@ -201,6 +264,377 @@ function resolveDefaultProfileDir() {
 	if (platform === "win32") return path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome", "User Data");
 	return path.join(home, ".config", "google-chrome");
 }
+const CONTENT_TRUNCATION_HINT = "Use a CSS selector to scope the content, or use mode=\"summary\" for a lower-token overview.";
+const LOCATOR_RUNTIME_HELPERS = String.raw`
+      const LOCATOR_SEPARATOR = ' >>> ';
+
+      function splitLocator(locator) {
+        return String(locator ?? '')
+          .split(/\s*>>>\s*/g)
+          .map((part) => part.trim())
+          .filter(Boolean);
+      }
+
+      function getFrameElementForDocument(doc) {
+        try {
+          return doc && doc.defaultView && doc.defaultView.frameElement ? doc.defaultView.frameElement : null;
+        } catch {
+          return null;
+        }
+      }
+
+      function createComposedChain(node) {
+        const chain = [];
+        let current = node;
+        while (current) {
+          chain.push(current);
+          if (current.parentNode) {
+            current = current.parentNode;
+            continue;
+          }
+          if (current.host) {
+            current = current.host;
+            continue;
+          }
+          if (current.nodeType === Node.DOCUMENT_NODE) {
+            current = getFrameElementForDocument(current);
+            continue;
+          }
+          current = null;
+        }
+        return chain;
+      }
+
+      function isSameComposedTarget(left, right) {
+        if (!left || !right) return false;
+        const seen = new Set(createComposedChain(left));
+        for (const current of createComposedChain(right)) {
+          if (seen.has(current)) {
+            return true;
+          }
+        }
+        return false;
+      }
+
+      function isWithinComposedSubtree(root, candidate) {
+        if (!root || !candidate) return false;
+        for (const current of createComposedChain(candidate)) {
+          if (current === root) {
+            return true;
+          }
+        }
+        return false;
+      }
+
+      function resolveLocator(locator) {
+        const parts = splitLocator(locator);
+        if (parts.length === 0) return null;
+
+        let root = document;
+        let element = null;
+        for (let index = 0; index < parts.length; index += 1) {
+          element = root.querySelector(parts[index]);
+          if (!element) return null;
+
+          if (index === parts.length - 1) {
+            return element;
+          }
+
+          if (element.tagName && element.tagName.toLowerCase() === 'iframe') {
+            let nextDocument = null;
+            try {
+              nextDocument = element.contentDocument;
+            } catch {
+              nextDocument = null;
+            }
+            if (!nextDocument) {
+              throw new Error('Unable to access iframe content for locator segment: ' + parts[index]);
+            }
+            root = nextDocument;
+            continue;
+          }
+
+          if (element.shadowRoot) {
+            root = element.shadowRoot;
+            continue;
+          }
+
+          throw new Error('Locator segment does not enter a shadow root or iframe: ' + parts[index]);
+        }
+
+        return element;
+      }
+
+      function resolveWithFallbacks(selector, fallbacks) {
+        let lastError = null;
+        const locators = [];
+        if (selector) locators.push(selector);
+        if (Array.isArray(fallbacks)) {
+          for (const fallback of fallbacks) {
+            locators.push(fallback);
+          }
+        }
+
+        for (const locator of locators) {
+          try {
+            const element = resolveLocator(locator);
+            if (element) {
+              return { element, locator };
+            }
+          } catch (error) {
+            lastError = error;
+          }
+        }
+
+        if (lastError) {
+          throw lastError;
+        }
+        throw new Error('Selector not found');
+      }
+
+      function ensureInView(element) {
+        if (element && typeof element.scrollIntoView === 'function') {
+          element.scrollIntoView({ block: 'center', inline: 'center' });
+        }
+      }
+
+      function toMainFramePoint(element) {
+        const rect = element.getBoundingClientRect();
+        let x = rect.left + rect.width / 2;
+        let y = rect.top + rect.height / 2;
+        let doc = element.ownerDocument;
+
+        while (doc) {
+          const frameElement = getFrameElementForDocument(doc);
+          if (!frameElement) {
+            break;
+          }
+          const frameRect = frameElement.getBoundingClientRect();
+          x += frameRect.left;
+          y += frameRect.top;
+          doc = frameElement.ownerDocument;
+        }
+
+        return { x, y, width: rect.width, height: rect.height };
+      }
+
+      function getTopFrameElement(element) {
+        let topFrame = null;
+        let doc = element.ownerDocument;
+        while (doc) {
+          const frameElement = getFrameElementForDocument(doc);
+          if (!frameElement) {
+            break;
+          }
+          topFrame = frameElement;
+          doc = frameElement.ownerDocument;
+        }
+        return topFrame;
+      }
+
+      function describeElement(element) {
+        if (!element || !element.tagName) return 'unknown';
+        const tag = element.tagName.toLowerCase();
+        const id = element.id ? '#' + element.id : '';
+        const className =
+          element.className && typeof element.className === 'string'
+            ? '.' + element.className.trim().split(/\s+/).filter(Boolean).join('.')
+            : '';
+        return tag + id + className;
+      }
+
+      function deepActiveElement() {
+        let current = document.activeElement;
+        while (current) {
+          if (current.shadowRoot && current.shadowRoot.activeElement) {
+            current = current.shadowRoot.activeElement;
+            continue;
+          }
+          if (current.tagName && current.tagName.toLowerCase() === 'iframe') {
+            try {
+              const frameActive = current.contentDocument && current.contentDocument.activeElement;
+              if (frameActive) {
+                current = frameActive;
+                continue;
+              }
+            } catch {
+              // ignore inaccessible frames
+            }
+          }
+          break;
+        }
+        return current;
+      }
+`;
+function buildLocatorRuntimeExpression(inputName, inputValue, body) {
+	return `(async () => {
+${LOCATOR_RUNTIME_HELPERS}
+      const ${inputName} = ${JSON.stringify(inputValue)};
+${body}
+    })()`;
+}
+const SPECIAL_KEY_PAYLOADS = new Map([
+	["Enter", {
+		key: "Enter",
+		code: "Enter",
+		windowsVirtualKeyCode: 13,
+		nativeVirtualKeyCode: 13,
+		text: "\r",
+		unmodifiedText: "\r"
+	}],
+	["Tab", {
+		key: "Tab",
+		code: "Tab",
+		windowsVirtualKeyCode: 9,
+		nativeVirtualKeyCode: 9
+	}],
+	["Escape", {
+		key: "Escape",
+		code: "Escape",
+		windowsVirtualKeyCode: 27,
+		nativeVirtualKeyCode: 27
+	}],
+	["Backspace", {
+		key: "Backspace",
+		code: "Backspace",
+		windowsVirtualKeyCode: 8,
+		nativeVirtualKeyCode: 8
+	}],
+	["Delete", {
+		key: "Delete",
+		code: "Delete",
+		windowsVirtualKeyCode: 46,
+		nativeVirtualKeyCode: 46
+	}],
+	["Space", {
+		key: " ",
+		code: "Space",
+		windowsVirtualKeyCode: 32,
+		nativeVirtualKeyCode: 32,
+		text: " ",
+		unmodifiedText: " "
+	}],
+	[" ", {
+		key: " ",
+		code: "Space",
+		windowsVirtualKeyCode: 32,
+		nativeVirtualKeyCode: 32,
+		text: " ",
+		unmodifiedText: " "
+	}],
+	["ArrowUp", {
+		key: "ArrowUp",
+		code: "ArrowUp",
+		windowsVirtualKeyCode: 38,
+		nativeVirtualKeyCode: 38
+	}],
+	["ArrowDown", {
+		key: "ArrowDown",
+		code: "ArrowDown",
+		windowsVirtualKeyCode: 40,
+		nativeVirtualKeyCode: 40
+	}],
+	["ArrowLeft", {
+		key: "ArrowLeft",
+		code: "ArrowLeft",
+		windowsVirtualKeyCode: 37,
+		nativeVirtualKeyCode: 37
+	}],
+	["ArrowRight", {
+		key: "ArrowRight",
+		code: "ArrowRight",
+		windowsVirtualKeyCode: 39,
+		nativeVirtualKeyCode: 39
+	}],
+	["Home", {
+		key: "Home",
+		code: "Home",
+		windowsVirtualKeyCode: 36,
+		nativeVirtualKeyCode: 36
+	}],
+	["End", {
+		key: "End",
+		code: "End",
+		windowsVirtualKeyCode: 35,
+		nativeVirtualKeyCode: 35
+	}],
+	["PageUp", {
+		key: "PageUp",
+		code: "PageUp",
+		windowsVirtualKeyCode: 33,
+		nativeVirtualKeyCode: 33
+	}],
+	["PageDown", {
+		key: "PageDown",
+		code: "PageDown",
+		windowsVirtualKeyCode: 34,
+		nativeVirtualKeyCode: 34
+	}]
+]);
+function appendTruncationNotice(content, limit, originalLength) {
+	return content + `\n\n[Truncated - showing first ${limit} of ${originalLength} characters. ${CONTENT_TRUNCATION_HINT}]`;
+}
+function applyContentLimit(content, limit, originalLength = content.length) {
+	if (!limit || originalLength <= limit) return {
+		content,
+		truncated: false
+	};
+	return {
+		content: appendTruncationNotice(content.slice(0, limit), limit, originalLength),
+		truncated: true,
+		originalLength
+	};
+}
+function normalizeRuntimeContentPayload(value, limit) {
+	if (typeof value === "string") {
+		const limited = applyContentLimit(value, limit);
+		return {
+			content: limited.content,
+			truncated: limited.truncated || void 0,
+			originalLength: limited.originalLength
+		};
+	}
+	const content = value?.content ?? "";
+	if (value?.truncated) {
+		const originalLength = value.originalLength ?? content.length;
+		const effectiveLimit = limit && limit > 0 ? limit : content.length;
+		return {
+			content: content.includes("[Truncated - showing first") || effectiveLimit === 0 ? content : appendTruncationNotice(content, effectiveLimit, originalLength),
+			truncated: true,
+			originalLength
+		};
+	}
+	const limited = applyContentLimit(content, limit, value?.originalLength ?? content.length);
+	return {
+		content: limited.content,
+		truncated: limited.truncated || void 0,
+		originalLength: limited.originalLength
+	};
+}
+function buildKeyDispatchPayload(inputKey) {
+	const key = inputKey || "Enter";
+	const special = SPECIAL_KEY_PAYLOADS.get(key);
+	if (special) return { ...special };
+	if (key.length === 1) {
+		const upper = key.toUpperCase();
+		const code = key >= "a" && key <= "z" ? `Key${upper}` : key >= "A" && key <= "Z" ? `Key${key}` : key >= "0" && key <= "9" ? `Digit${key}` : "Unidentified";
+		const keyCode = upper.charCodeAt(0);
+		return {
+			key,
+			code,
+			windowsVirtualKeyCode: keyCode,
+			nativeVirtualKeyCode: keyCode,
+			text: key,
+			unmodifiedText: key
+		};
+	}
+	return {
+		key,
+		code: key,
+		windowsVirtualKeyCode: 0,
+		nativeVirtualKeyCode: 0
+	};
+}
 var ChromeCdpBrowserController = class {
 	connections = /* @__PURE__ */ new Map();
 	cleanupInterval;
@@ -283,7 +717,6 @@ var ChromeCdpBrowserController = class {
 	async launch(sessionId, options) {
 		const { executablePath: explicitPath, userProfileDir, headless, userAgent } = options ?? {};
 		const executablePath = discoverChrome(explicitPath);
-		const extension = loadControlExtension();
 		let profileDir;
 		if (userProfileDir === "default") profileDir = resolveDefaultProfileDir();
 		else if (userProfileDir) profileDir = userProfileDir;
@@ -291,23 +724,7 @@ var ChromeCdpBrowserController = class {
 		fs.mkdirSync(profileDir, { recursive: true });
 		const lockFile = path.join(profileDir, "SingletonLock");
 		if (fs.existsSync(lockFile)) throw new Error(`Chrome profile is already in use (lock file exists: ${lockFile}). Quit the running Chrome instance first, or use --cdp-url to connect to it instead.`);
-		const launchAttempts = headless ? [{
-			withExtension: false,
-			headless: true
-		}] : [
-			{
-				withExtension: true,
-				headless: false
-			},
-			{
-				withExtension: false,
-				headless: false
-			},
-			{
-				withExtension: false,
-				headless: true
-			}
-		];
+		const launchAttempts = headless ? [{ headless: true }] : [{ headless: false }, { headless: true }];
 		let lastError;
 		for (const attempt of launchAttempts) {
 			const port = await getFreePort();
@@ -317,7 +734,6 @@ var ChromeCdpBrowserController = class {
 				"--no-first-run",
 				"--no-default-browser-check"
 			];
-			if (attempt.withExtension) args.push(`--disable-extensions-except=${extension.extensionPath}`, `--load-extension=${extension.extensionPath}`);
 			if (attempt.headless) args.push("--headless=new");
 			args.push("about:blank");
 			const child = spawn(executablePath, args, {
@@ -392,6 +808,151 @@ var ChromeCdpBrowserController = class {
 			return `${result}: ${dialog.message}`;
 		});
 	}
+	async preparePointerTarget(conn, payload) {
+		const expression = buildLocatorRuntimeExpression("payload", payload, `
+      const resolved = resolveWithFallbacks(payload.selector, payload.fallbackSelectors);
+      const el = resolved.element;
+      ensureInView(el);
+
+      const point = toMainFramePoint(el);
+      if (point.width === 0 && point.height === 0) {
+        throw new Error('Element has zero size - it may be hidden or not rendered');
+      }
+
+      const topEl = document.elementFromPoint(point.x, point.y);
+      const topFrame = getTopFrameElement(el);
+      if (topEl && !isSameComposedTarget(topEl, el) && (!topFrame || topEl !== topFrame)) {
+        throw new Error('Element is covered by another element: ' + describeElement(topEl));
+      }
+
+      return { x: point.x, y: point.y };
+`);
+		const point = (await conn.send("Runtime.evaluate", {
+			expression,
+			returnByValue: true,
+			awaitPromise: true
+		})).result.value;
+		if (!point || typeof point.x !== "number" || typeof point.y !== "number") throw new Error("Unable to resolve pointer target");
+		return {
+			x: point.x,
+			y: point.y
+		};
+	}
+	async prepareTypeTarget(conn, payload) {
+		const expression = buildLocatorRuntimeExpression("payload", payload, `
+      const resolved = resolveWithFallbacks(payload.selector, payload.fallbackSelectors);
+      const el = resolved.element;
+      ensureInView(el);
+
+      const point = toMainFramePoint(el);
+      if (point.width === 0 && point.height === 0) {
+        throw new Error('Element has zero size - it may be hidden or not rendered');
+      }
+
+      const tag = el.tagName.toLowerCase();
+      const inputType = tag === 'input' ? (el.type || 'text').toLowerCase() : '';
+      const editable =
+        el.isContentEditable ||
+        tag === 'textarea' ||
+        (tag === 'input' &&
+          !['checkbox', 'radio', 'button', 'submit', 'reset', 'file', 'hidden'].includes(inputType));
+
+      if (!editable) {
+        throw new Error('Element is not text-editable');
+      }
+
+      if (typeof el.focus === 'function') {
+        el.focus();
+      }
+
+      if ((payload.text ?? '') === '') {
+        if (el.isContentEditable) {
+          el.textContent = '';
+        } else if ('value' in el) {
+          el.value = '';
+        }
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        return 'cleared';
+      }
+
+      if (el.isContentEditable) {
+        const selection = el.ownerDocument.getSelection ? el.ownerDocument.getSelection() : null;
+        if (selection) {
+          const range = el.ownerDocument.createRange();
+          range.selectNodeContents(el);
+          selection.removeAllRanges();
+          selection.addRange(range);
+        }
+      } else if (typeof el.select === 'function') {
+        el.select();
+      }
+
+      return 'ready';
+`);
+		return (await conn.send("Runtime.evaluate", {
+			expression,
+			returnByValue: true,
+			awaitPromise: true
+		})).result.value ?? "ready";
+	}
+	async dispatchMouseClick(conn, x, y) {
+		await conn.send("Input.dispatchMouseEvent", {
+			type: "mouseMoved",
+			x,
+			y,
+			button: "none"
+		});
+		await conn.send("Input.dispatchMouseEvent", {
+			type: "mousePressed",
+			x,
+			y,
+			button: "left",
+			clickCount: 1
+		});
+		await conn.send("Input.dispatchMouseEvent", {
+			type: "mouseReleased",
+			x,
+			y,
+			button: "left",
+			clickCount: 1
+		});
+	}
+	async focusTarget(conn, payload) {
+		if (!payload.selector) return;
+		const expression = buildLocatorRuntimeExpression("payload", payload, `
+      const resolved = resolveWithFallbacks(payload.selector, payload.fallbackSelectors);
+      const el = resolved.element;
+      ensureInView(el);
+      if (typeof el.focus === 'function') {
+        el.focus();
+      }
+      return true;
+`);
+		await conn.send("Runtime.evaluate", {
+			expression,
+			returnByValue: true,
+			awaitPromise: true
+		});
+	}
+	async dispatchKeyPress(conn, keyInput) {
+		const payload = buildKeyDispatchPayload(keyInput ?? "Enter");
+		await conn.send("Input.dispatchKeyEvent", {
+			type: payload.text ? "keyDown" : "rawKeyDown",
+			key: payload.key,
+			code: payload.code,
+			windowsVirtualKeyCode: payload.windowsVirtualKeyCode,
+			nativeVirtualKeyCode: payload.nativeVirtualKeyCode,
+			text: payload.text,
+			unmodifiedText: payload.unmodifiedText
+		});
+		await conn.send("Input.dispatchKeyEvent", {
+			type: "keyUp",
+			key: payload.key,
+			code: payload.code,
+			windowsVirtualKeyCode: payload.windowsVirtualKeyCode,
+			nativeVirtualKeyCode: payload.nativeVirtualKeyCode
+		});
+	}
 	async interact(targetWsUrl, payload) {
 		if (payload.action === "goBack") return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
@@ -430,59 +991,43 @@ var ChromeCdpBrowserController = class {
 			return "page refreshed";
 		});
 		if (payload.action === "dialog") return await this.handleDialogAction(targetWsUrl, payload);
-		const expression = `(async () => {
-      const payload = ${JSON.stringify(payload)};
-
-      function resolveElement(selector, fallbacks) {
-        let el = selector ? document.querySelector(selector) : null;
-        if (el) return el;
-        if (fallbacks && fallbacks.length) {
-          for (const fb of fallbacks) {
-            el = document.querySelector(fb);
-            if (el) return el;
-          }
-        }
-        throw new Error('Selector not found');
-      }
-
-      if (payload.action === 'click') {
-        const el = resolveElement(payload.selector, payload.fallbackSelectors);
-        const rect = el.getBoundingClientRect();
-        if (rect.width === 0 && rect.height === 0) {
-          throw new Error('Element has zero size – it may be hidden or not rendered');
-        }
-        const cx = rect.left + rect.width / 2;
-        const cy = rect.top + rect.height / 2;
-        const topEl = document.elementFromPoint(cx, cy);
-        if (topEl && topEl !== el && !el.contains(topEl) && !topEl.contains(el)) {
-          const tag = topEl.tagName.toLowerCase();
-          const id = topEl.id ? '#' + topEl.id : '';
-          const cls = topEl.className && typeof topEl.className === 'string' ? '.' + topEl.className.split(' ').join('.') : '';
-          throw new Error('Element is covered by another element: ' + tag + id + cls);
-        }
-        el.click();
-        return 'clicked';
-      }
-      if (payload.action === 'type') {
-        const el = resolveElement(payload.selector, payload.fallbackSelectors);
-        el.focus();
-        el.value = payload.text ?? '';
-        el.dispatchEvent(new Event('input', { bubbles: true }));
-        return 'typed';
-      }
-      if (payload.action === 'press') {
-        const target = document.activeElement;
-        if (!target) throw new Error('No active element to press key on');
-        const key = payload.key ?? 'Enter';
-        target.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
-        target.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
-        return 'pressed';
-      }
+		if (payload.action === "click" || payload.action === "hover" || payload.action === "type" || payload.action === "press") return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			if (payload.action === "click") {
+				const point = await this.preparePointerTarget(conn, payload);
+				await this.dispatchMouseClick(conn, point.x, point.y);
+				try {
+					await conn.waitForEvent("Page.frameNavigated", 50);
+					try {
+						await Promise.race([conn.waitForEvent("Page.loadEventFired", 3e3), conn.waitForEvent("Page.frameStoppedLoading", 3e3)]);
+					} catch {}
+				} catch {}
+				return "clicked";
+			}
+			if (payload.action === "hover") {
+				const point = await this.preparePointerTarget(conn, payload);
+				await conn.send("Input.dispatchMouseEvent", {
+					type: "mouseMoved",
+					x: point.x,
+					y: point.y,
+					button: "none"
+				});
+				return "hovered";
+			}
+			if (payload.action === "press") {
+				await this.focusTarget(conn, payload);
+				await this.dispatchKeyPress(conn, payload.key);
+				return "pressed";
+			}
+			if (await this.prepareTypeTarget(conn, payload) === "ready") await conn.send("Input.insertText", { text: payload.text ?? "" });
+			return "typed";
+		});
+		const expression = buildLocatorRuntimeExpression("payload", payload, `
       if (payload.action === 'waitFor') {
         const timeout = payload.timeoutMs ?? 2000;
         const started = Date.now();
         while (Date.now() - started < timeout) {
-          if (document.querySelector(payload.selector)) {
+          if (resolveLocator(payload.selector)) {
             return 'found';
           }
           await new Promise((resolve) => setTimeout(resolve, 100));
@@ -499,25 +1044,15 @@ var ChromeCdpBrowserController = class {
       }
       if (payload.action === 'scroll') {
         if (payload.selector) {
-          const el = resolveElement(payload.selector, payload.fallbackSelectors);
-          el.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0, behavior: 'smooth' });
+          const el = resolveWithFallbacks(payload.selector, payload.fallbackSelectors).element;
+          el.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0 });
           return 'scrolled element';
         }
-        window.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0, behavior: 'smooth' });
+        window.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0 });
         return 'scrolled page';
       }
-      if (payload.action === 'hover') {
-        const el = resolveElement(payload.selector, payload.fallbackSelectors);
-        const rect = el.getBoundingClientRect();
-        const cx = rect.left + rect.width / 2;
-        const cy = rect.top + rect.height / 2;
-        el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true, clientX: cx, clientY: cy }));
-        el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true, clientX: cx, clientY: cy }));
-        el.dispatchEvent(new MouseEvent('mousemove', { bubbles: true, clientX: cx, clientY: cy }));
-        return 'hovered';
-      }
       if (payload.action === 'select') {
-        const el = resolveElement(payload.selector, payload.fallbackSelectors);
+        const el = resolveWithFallbacks(payload.selector, payload.fallbackSelectors).element;
         if (el.tagName.toLowerCase() !== 'select') throw new Error('Element is not a <select>');
         el.value = payload.value ?? '';
         el.dispatchEvent(new Event('change', { bubbles: true }));
@@ -525,120 +1060,333 @@ var ChromeCdpBrowserController = class {
         return 'selected ' + el.value;
       }
       if (payload.action === 'toggle') {
-        const el = resolveElement(payload.selector, payload.fallbackSelectors);
+        const el = resolveWithFallbacks(payload.selector, payload.fallbackSelectors).element;
         el.click();
         const checked = el.checked !== undefined ? el.checked : el.getAttribute('aria-checked') === 'true';
         return 'toggled to ' + (checked ? 'checked' : 'unchecked');
       }
       throw new Error('Unsupported interact action');
-    })()`;
+`);
 		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			const value = (await conn.send("Runtime.evaluate", {
+			return (await conn.send("Runtime.evaluate", {
 				expression,
 				returnByValue: true,
 				awaitPromise: true
 			})).result.value ?? "";
-			if (payload.action === "click" && value === "clicked") try {
-				await conn.waitForEvent("Page.frameNavigated", 50);
-				try {
-					await Promise.race([conn.waitForEvent("Page.loadEventFired", 3e3), conn.waitForEvent("Page.frameStoppedLoading", 3e3)]);
-				} catch {}
-			} catch {}
-			return value;
 		});
 	}
 	async getContent(targetWsUrl, options) {
-		if (options.mode === "a11y") return {
-			mode: "a11y",
-			content: await this.getAccessibilityTree(targetWsUrl)
-		};
-		const expression = `(() => {
-      const options = ${JSON.stringify(options)};
-      if (options.mode === 'title') return document.title ?? '';
+		if (options.mode === "summary") return await this.getSummaryContent(targetWsUrl, options);
+		if (options.mode === "a11y") {
+			const limited = normalizeRuntimeContentPayload(await this.getAccessibilityTree(targetWsUrl, options.selector), options.maxChars);
+			return {
+				mode: "a11y",
+				content: limited.content,
+				truncated: limited.truncated,
+				originalLength: limited.originalLength
+			};
+		}
+		const expression = buildLocatorRuntimeExpression("options", options, `
+      const limit =
+        typeof options.maxChars === 'number' && Number.isFinite(options.maxChars) && options.maxChars > 0
+          ? Math.floor(options.maxChars)
+          : null;
+
+      function serializeContent(content) {
+        const normalized = typeof content === 'string' ? content : String(content ?? '');
+        const originalLength = normalized.length;
+        if (limit !== null && originalLength > limit) {
+          return { content: normalized.slice(0, limit), truncated: true, originalLength };
+        }
+        return { content: normalized, truncated: false, originalLength };
+      }
+
+      if (options.mode === 'title') return serializeContent(document.title ?? '');
       if (options.mode === 'html') {
         if (options.selector) {
-          const el = document.querySelector(options.selector);
-          return el ? el.outerHTML : '';
+          const el = resolveLocator(options.selector);
+          return serializeContent(el ? el.outerHTML : '');
         }
-        return document.documentElement?.outerHTML ?? '';
+        return serializeContent(document.documentElement?.outerHTML ?? '');
       }
       if (options.selector) {
-        const el = document.querySelector(options.selector);
-        return el ? el.innerText ?? '' : '';
+        const el = resolveLocator(options.selector);
+        return serializeContent(el ? el.innerText ?? '' : '');
       }
-      return document.body?.innerText ?? '';
-    })()`;
+      return serializeContent(document.body?.innerText ?? '');
+`);
 		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			const content = (await conn.send("Runtime.evaluate", {
+			const limited = normalizeRuntimeContentPayload((await conn.send("Runtime.evaluate", {
 				expression,
-				returnByValue: true
-			})).result.value ?? "";
+				returnByValue: true,
+				awaitPromise: true
+			})).result.value, options.maxChars);
 			return {
 				mode: options.mode,
-				content
+				content: limited.content,
+				truncated: limited.truncated,
+				originalLength: limited.originalLength
 			};
 		});
 	}
-	async getAccessibilityTree(targetWsUrl) {
-		return await this.withRetry(targetWsUrl, async (conn) => {
-			await conn.send("Accessibility.enable");
-			const { nodes } = await conn.send("Accessibility.getFullAXTree");
-			const childrenMap = /* @__PURE__ */ new Map();
-			const nodeMap = /* @__PURE__ */ new Map();
-			for (const node of nodes) {
-				nodeMap.set(node.nodeId, node);
-				if (node.parentId) {
-					const siblings = childrenMap.get(node.parentId);
-					if (siblings) siblings.push(node.nodeId);
-					else childrenMap.set(node.parentId, [node.nodeId]);
+	summarizeInteractiveElements(result) {
+		const primaryActions = [];
+		const inputs = [];
+		for (const element of result.elements) {
+			if (primaryActions.length < 8 && (element.role === "button" || element.role === "link" || element.role === "custom")) primaryActions.push({
+				role: element.role,
+				text: element.text,
+				selector: element.selector,
+				fallbackSelectors: element.fallbackSelectors,
+				href: element.href
+			});
+			if (inputs.length < 8 && (element.role === "input" || element.role === "textarea" || element.role === "select" || element.role === "checkbox" || element.role === "radio" || element.role === "contenteditable")) inputs.push({
+				role: element.role,
+				text: element.text,
+				selector: element.selector,
+				fallbackSelectors: element.fallbackSelectors,
+				inputType: element.inputType,
+				placeholder: element.placeholder,
+				ariaLabel: element.ariaLabel
+			});
+			if (primaryActions.length >= 8 && inputs.length >= 8) break;
+		}
+		return {
+			primaryActions,
+			inputs
+		};
+	}
+	async getSummaryContent(targetWsUrl, options) {
+		const expression = buildLocatorRuntimeExpression("options", options, `
+      const scopeSelector = options.selector;
+      let scopeRoot = document.body ?? document.documentElement;
+      if (scopeSelector) {
+        try {
+          scopeRoot = resolveLocator(scopeSelector) ?? scopeRoot;
+        } catch {
+          scopeRoot = scopeRoot ?? document.documentElement;
+        }
+      }
+
+      function escapeAttr(value) {
+        return String(value ?? '').replace(/\\\\/g, '\\\\\\\\').replace(/"/g, '\\\\"');
+      }
+
+      function uniqueValues(values, limit) {
+        const seen = new Set();
+        const results = [];
+        for (const value of values) {
+          const normalized = String(value ?? '').replace(/\\s+/g, ' ').trim();
+          if (!normalized || seen.has(normalized)) continue;
+          seen.add(normalized);
+          results.push(normalized.slice(0, 160));
+          if (results.length >= limit) break;
+        }
+        return results;
+      }
+
+      function textOf(el) {
+        if (!el) return '';
+        const ariaLabel = el.getAttribute && el.getAttribute('aria-label');
+        if (ariaLabel) return ariaLabel;
+        const text = el.innerText || el.textContent || '';
+        return text.replace(/\\s+/g, ' ').trim();
+      }
+
+      function frameSelector(frame) {
+        if (frame.id) return '#' + CSS.escape(frame.id);
+        const name = frame.getAttribute('name');
+        if (name) return 'iframe[name="' + escapeAttr(name) + '"]';
+        const title = frame.getAttribute('title');
+        if (title) return 'iframe[title="' + escapeAttr(title) + '"]';
+        const src = frame.getAttribute('src');
+        if (src) return 'iframe[src="' + escapeAttr(src) + '"]';
+        const parent = frame.parentElement;
+        if (!parent) return 'iframe';
+        const siblings = Array.from(parent.children).filter((candidate) => candidate.tagName === frame.tagName);
+        if (siblings.length === 1) return 'iframe';
+        return 'iframe:nth-of-type(' + (siblings.indexOf(frame) + 1) + ')';
+      }
+
+      const headingSelectors = 'h1,h2,h3,h4,h5,h6,[role="heading"]';
+      const landmarkSelectors = [
+        'main',
+        'nav',
+        'aside',
+        'header',
+        'footer',
+        '[role="main"]',
+        '[role="navigation"]',
+        '[role="banner"]',
+        '[role="complementary"]',
+        '[role="contentinfo"]',
+        '[role="search"]'
+      ].join(',');
+      const alertSelectors = '[role="alert"], [aria-live="assertive"], dialog[open], [aria-modal="true"]';
+
+      const headings = uniqueValues(
+        Array.from(scopeRoot.querySelectorAll(headingSelectors)).map((el) => textOf(el)),
+        8
+      );
+      const landmarks = uniqueValues(
+        Array.from(scopeRoot.querySelectorAll(landmarkSelectors)).map((el) => {
+          const role = el.getAttribute('role') || el.tagName.toLowerCase();
+          const label = textOf(el);
+          return label ? role + ' "' + label.slice(0, 80) + '"' : role;
+        }),
+        8
+      );
+      const alerts = uniqueValues(
+        Array.from(scopeRoot.querySelectorAll(alertSelectors)).map((el) => textOf(el)),
+        6
+      );
+
+      const allFrames = Array.from(scopeRoot.querySelectorAll('iframe'));
+      const frames = allFrames.slice(0, 8).map((frame) => {
+        let sameOrigin = false;
+        try {
+          sameOrigin = !!frame.contentDocument;
+        } catch {
+          sameOrigin = false;
+        }
+
+        return {
+          selector: frameSelector(frame),
+          name: frame.getAttribute('name') || undefined,
+          title: frame.getAttribute('title') || undefined,
+          src: frame.getAttribute('src') || frame.src || undefined,
+          sameOrigin,
+        };
+      });
+
+      return {
+        url: window.location.href,
+        title: document.title ?? '',
+        headings,
+        landmarks,
+        alerts,
+        frames,
+        crossOriginFrameCount: allFrames.filter((frame) => {
+          try {
+            return !frame.contentDocument;
+          } catch {
+            return true;
+          }
+        }).length,
+        hasMoreFrames: allFrames.length > frames.length,
+        scopedToSelector: scopeSelector || undefined,
+      };
+`);
+		const pageSummary = await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			return (await conn.send("Runtime.evaluate", {
+				expression,
+				returnByValue: true,
+				awaitPromise: true
+			})).result.value ?? {};
+		});
+		const elements = await this.getInteractiveElements(targetWsUrl, {
+			selector: options.selector,
+			visibleOnly: true,
+			limit: 24
+		});
+		const elementSummary = this.summarizeInteractiveElements(elements);
+		return {
+			mode: "summary",
+			content: "",
+			structuredContent: {
+				mode: "summary",
+				...pageSummary,
+				...elementSummary,
+				totalInteractiveElements: elements.totalFound,
+				truncatedInteractiveElements: elements.truncated
+			}
+		};
+	}
+	formatAccessibilityTree(nodes) {
+		const childrenMap = /* @__PURE__ */ new Map();
+		const nodeMap = /* @__PURE__ */ new Map();
+		for (const node of nodes) {
+			nodeMap.set(node.nodeId, node);
+			if (node.parentId) {
+				const siblings = childrenMap.get(node.parentId);
+				if (siblings) siblings.push(node.nodeId);
+				else childrenMap.set(node.parentId, [node.nodeId]);
+			}
+		}
+		const lines = [];
+		const formatNode = (nodeId, depth) => {
+			const node = nodeMap.get(nodeId);
+			if (!node) return;
+			const role = node.role?.value ?? "unknown";
+			const name = node.name?.value ?? "";
+			const value = node.value?.value ?? "";
+			if (node.ignored) {
+				const children = childrenMap.get(nodeId) ?? node.childIds ?? [];
+				for (const childId of children) formatNode(childId, depth);
+				return;
+			}
+			const skip = !name && !value && (role === "generic" || role === "none" || role === "GenericContainer");
+			if (!skip) {
+				let line = `${"  ".repeat(depth)}${role}`;
+				if (name) line += ` "${name}"`;
+				if (value) line += ` value="${value}"`;
+				if (node.properties) {
+					for (const prop of node.properties) if (prop.value.value === true) line += ` [${prop.name}]`;
+					else if (prop.name === "checked" && prop.value.value === "mixed") line += ` [indeterminate]`;
 				}
+				lines.push(line);
 			}
-			const lines = [];
-			const formatNode = (nodeId, depth) => {
-				const node = nodeMap.get(nodeId);
-				if (!node) return;
-				const role = node.role?.value ?? "unknown";
-				const name = node.name?.value ?? "";
-				const value = node.value?.value ?? "";
-				if (node.ignored) {
-					const children = childrenMap.get(nodeId) ?? node.childIds ?? [];
-					for (const childId of children) formatNode(childId, depth);
-					return;
+			const children = childrenMap.get(nodeId) ?? node.childIds ?? [];
+			for (const childId of children) formatNode(childId, skip ? depth : depth + 1);
+		};
+		const roots = nodes.filter((node) => !node.parentId || !nodeMap.has(node.parentId));
+		for (const root of roots) formatNode(root.nodeId, 0);
+		return lines.join("\n");
+	}
+	async getAccessibilityTree(targetWsUrl, selector) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			await conn.send("Accessibility.enable");
+			let nodes;
+			if (selector) {
+				const objectGroup = "agentic-browser-a11y";
+				const selected = await conn.send("Runtime.evaluate", {
+					expression: buildLocatorRuntimeExpression("selector", selector, `
+      return resolveLocator(selector);
+`),
+					objectGroup
+				});
+				const objectId = selected.result.objectId;
+				if (!objectId || selected.result.subtype === "null") {
+					try {
+						await conn.send("Runtime.releaseObjectGroup", { objectGroup });
+					} catch {}
+					return "";
 				}
-				const skip = !name && !value && (role === "generic" || role === "none" || role === "GenericContainer");
-				if (!skip) {
-					let line = `${"  ".repeat(depth)}${role}`;
-					if (name) line += ` "${name}"`;
-					if (value) line += ` value="${value}"`;
-					if (node.properties) {
-						for (const prop of node.properties) if (prop.value.value === true) line += ` [${prop.name}]`;
-						else if (prop.name === "checked" && prop.value.value === "mixed") line += ` [indeterminate]`;
-					}
-					lines.push(line);
+				try {
+					nodes = (await conn.send("Accessibility.getPartialAXTree", {
+						objectId,
+						fetchRelatives: false
+					})).nodes;
+				} finally {
+					try {
+						await conn.send("Runtime.releaseObjectGroup", { objectGroup });
+					} catch {}
 				}
-				const children = childrenMap.get(nodeId) ?? node.childIds ?? [];
-				for (const childId of children) formatNode(childId, skip ? depth : depth + 1);
-			};
-			const roots = nodes.filter((n) => !n.parentId);
-			for (const root of roots) formatNode(root.nodeId, 0);
-			return lines.join("\n");
+			} else nodes = (await conn.send("Accessibility.getFullAXTree")).nodes;
+			return this.formatAccessibilityTree(nodes);
 		});
 	}
 	async getInteractiveElements(targetWsUrl, options) {
-		const expression = `(() => {
-      const options = ${JSON.stringify(options)};
+		const expression = buildLocatorRuntimeExpression("options", options, `
       const visibleOnly = options.visibleOnly !== false;
       const limit = options.limit ?? 50;
       const scopeSelector = options.selector;
       const roleFilter = options.roles ? new Set(options.roles) : null;
-
-      const root = scopeSelector
-        ? document.querySelector(scopeSelector) ?? document.body
-        : document.body;
-
-      const candidates = root.querySelectorAll([
+      const candidateSelector = [
         'a[href]',
         'button',
         'input:not([type="hidden"])',
@@ -654,43 +1402,15 @@ var ChromeCdpBrowserController = class {
         '[onclick]',
         '[tabindex]',
         '[contenteditable="true"]',
-        '[contenteditable=""]',
-      ].join(','));
-
-      const seen = new Set();
-
-      function classifyRole(el) {
-        const tag = el.tagName.toLowerCase();
-        const ariaRole = el.getAttribute('role');
-        if (tag === 'a') return 'link';
-        if (tag === 'button' || ariaRole === 'button') return 'button';
-        if (tag === 'input') {
-          const t = (el.type || 'text').toLowerCase();
-          if (t === 'checkbox') return 'checkbox';
-          if (t === 'radio') return 'radio';
-          return 'input';
-        }
-        if (tag === 'select') return 'select';
-        if (tag === 'textarea') return 'textarea';
-        if (el.isContentEditable) return 'contenteditable';
-        if (ariaRole === 'link') return 'link';
-        if (ariaRole === 'checkbox' || ariaRole === 'switch') return 'checkbox';
-        if (ariaRole === 'radio') return 'radio';
-        return 'custom';
-      }
-
-      function getActions(role, el) {
-        switch (role) {
-          case 'link': case 'button': case 'custom': return ['click'];
-          case 'input': {
-            const t = (el.type || 'text').toLowerCase();
-            if (t === 'submit' || t === 'reset' || t === 'button' || t === 'file') return ['click'];
-            return ['click', 'type', 'press'];
-          }
-          case 'textarea': case 'contenteditable': return ['click', 'type', 'press'];
-          case 'select': return ['click', 'select'];
-          case 'checkbox': case 'radio': return ['click', 'toggle'];
-          default: return ['click'];
+        '[contenteditable=""]'
+      ].join(',');
+
+      let scopeElement = null;
+      if (scopeSelector) {
+        try {
+          scopeElement = resolveLocator(scopeSelector) ?? document.body;
+        } catch {
+          scopeElement = document.body;
         }
       }
 
@@ -698,79 +1418,90 @@ var ChromeCdpBrowserController = class {
         return value.replace(/\\\\/g, '\\\\\\\\').replace(/"/g, '\\\\"');
       }
 
-      function tryUniqueSelector(sel) {
-        try { return document.querySelectorAll(sel).length === 1 ? sel : null; }
-        catch { return null; }
+      function composeLocator(path, selector) {
+        if (!path.length) return selector;
+        return path.join(LOCATOR_SEPARATOR) + LOCATOR_SEPARATOR + selector;
+      }
+
+      function tryUniqueSelector(root, selector) {
+        try {
+          return root.querySelectorAll(selector).length === 1 ? selector : null;
+        } catch {
+          return null;
+        }
       }
 
-      function buildSelector(el) {
+      function buildSelector(root, el) {
         if (el.id) return '#' + CSS.escape(el.id);
 
         const name = el.getAttribute('name');
         if (name) {
           const tag = el.tagName.toLowerCase();
-          const sel = tryUniqueSelector(tag + '[name="' + escapeAttr(name) + '"]');
-          if (sel) return sel;
+          const selector = tryUniqueSelector(root, tag + '[name="' + escapeAttr(name) + '"]');
+          if (selector) return selector;
         }
 
         const testId = el.getAttribute('data-testid') || el.getAttribute('data-test-id');
         if (testId) {
           const attr = el.hasAttribute('data-testid') ? 'data-testid' : 'data-test-id';
-          const sel = tryUniqueSelector('[' + attr + '="' + escapeAttr(testId) + '"]');
-          if (sel) return sel;
+          const selector = tryUniqueSelector(root, '[' + attr + '="' + escapeAttr(testId) + '"]');
+          if (selector) return selector;
         }
 
         const ariaLabel = el.getAttribute('aria-label');
         if (ariaLabel) {
           const tag = el.tagName.toLowerCase();
-          const sel = tryUniqueSelector(tag + '[aria-label="' + escapeAttr(ariaLabel) + '"]');
-          if (sel) return sel;
+          const selector = tryUniqueSelector(root, tag + '[aria-label="' + escapeAttr(ariaLabel) + '"]');
+          if (selector) return selector;
         }
 
         const dataCy = el.getAttribute('data-cy');
         if (dataCy) {
-          const sel = tryUniqueSelector('[data-cy="' + escapeAttr(dataCy) + '"]');
-          if (sel) return sel;
+          const selector = tryUniqueSelector(root, '[data-cy="' + escapeAttr(dataCy) + '"]');
+          if (selector) return selector;
         }
 
         const dataTest = el.getAttribute('data-test');
         if (dataTest) {
-          const sel = tryUniqueSelector('[data-test="' + escapeAttr(dataTest) + '"]');
-          if (sel) return sel;
+          const selector = tryUniqueSelector(root, '[data-test="' + escapeAttr(dataTest) + '"]');
+          if (selector) return selector;
         }
 
         const role = el.getAttribute('role');
         if (role && ariaLabel) {
-          const sel = tryUniqueSelector('[role="' + escapeAttr(role) + '"][aria-label="' + escapeAttr(ariaLabel) + '"]');
-          if (sel) return sel;
+          const selector = tryUniqueSelector(
+            root,
+            '[role="' + escapeAttr(role) + '"][aria-label="' + escapeAttr(ariaLabel) + '"]'
+          );
+          if (selector) return selector;
         }
 
-        // Path fallback — anchor at nearest ancestor with an id for shorter selectors
         const parts = [];
         let current = el;
-        while (current && current !== document.documentElement) {
+        while (current && current.nodeType === 1) {
           const tag = current.tagName.toLowerCase();
           if (current !== el && current.id) {
             parts.unshift('#' + CSS.escape(current.id));
             break;
           }
           const parent = current.parentElement;
-          if (!parent) { parts.unshift(tag); break; }
-          const siblings = Array.from(parent.children).filter(
-            c => c.tagName === current.tagName
-          );
+          if (!parent) {
+            parts.unshift(tag);
+            break;
+          }
+          const siblings = Array.from(parent.children).filter((candidate) => candidate.tagName === current.tagName);
           if (siblings.length === 1) {
             parts.unshift(tag);
           } else {
-            const idx = siblings.indexOf(current) + 1;
-            parts.unshift(tag + ':nth-of-type(' + idx + ')');
+            const index = siblings.indexOf(current) + 1;
+            parts.unshift(tag + ':nth-of-type(' + index + ')');
           }
           current = parent;
         }
         return parts.join(' > ');
       }
 
-      function buildFallbackSelectors(el, primarySelector) {
+      function buildFallbackSelectors(root, path, el, primarySelector) {
         const fallbacks = [];
         const candidates = [];
 
@@ -779,8 +1510,7 @@ var ChromeCdpBrowserController = class {
         const name = el.getAttribute('name');
         if (name) {
           const tag = el.tagName.toLowerCase();
-          const sel = tag + '[name="' + escapeAttr(name) + '"]';
-          candidates.push(sel);
+          candidates.push(tag + '[name="' + escapeAttr(name) + '"]');
         }
 
         const testId = el.getAttribute('data-testid') || el.getAttribute('data-test-id');
@@ -806,16 +1536,68 @@ var ChromeCdpBrowserController = class {
           candidates.push('[role="' + escapeAttr(role) + '"][aria-label="' + escapeAttr(ariaLabel) + '"]');
         }
 
-        for (const sel of candidates) {
-          if (sel === primarySelector) continue;
-          if (tryUniqueSelector(sel)) fallbacks.push(sel);
+        for (const candidate of candidates) {
+          if (!tryUniqueSelector(root, candidate)) continue;
+          const locator = composeLocator(path, candidate);
+          if (locator === primarySelector) continue;
+          fallbacks.push(locator);
           if (fallbacks.length >= 3) break;
         }
         return fallbacks;
       }
 
+      function classifyRole(el) {
+        const tag = el.tagName.toLowerCase();
+        const ariaRole = el.getAttribute('role');
+        if (tag === 'a') return 'link';
+        if (tag === 'button' || ariaRole === 'button') return 'button';
+        if (tag === 'input') {
+          const type = (el.type || 'text').toLowerCase();
+          if (type === 'checkbox') return 'checkbox';
+          if (type === 'radio') return 'radio';
+          return 'input';
+        }
+        if (tag === 'select') return 'select';
+        if (tag === 'textarea') return 'textarea';
+        if (el.isContentEditable) return 'contenteditable';
+        if (ariaRole === 'link') return 'link';
+        if (ariaRole === 'checkbox' || ariaRole === 'switch') return 'checkbox';
+        if (ariaRole === 'radio') return 'radio';
+        return 'custom';
+      }
+
+      function getActions(role, el) {
+        switch (role) {
+          case 'link':
+          case 'button':
+          case 'custom':
+            return ['click'];
+          case 'input': {
+            const type = (el.type || 'text').toLowerCase();
+            if (type === 'submit' || type === 'reset' || type === 'button' || type === 'file') {
+              return ['click'];
+            }
+            return ['click', 'type', 'press'];
+          }
+          case 'textarea':
+          case 'contenteditable':
+            return ['click', 'type', 'press'];
+          case 'select':
+            return ['click', 'select'];
+          case 'checkbox':
+          case 'radio':
+            return ['click', 'toggle'];
+          default:
+            return ['click'];
+        }
+      }
+
+      function viewForElement(el) {
+        return el.ownerDocument && el.ownerDocument.defaultView ? el.ownerDocument.defaultView : window;
+      }
+
       function isVisible(el) {
-        const style = window.getComputedStyle(el);
+        const style = viewForElement(el).getComputedStyle(el);
         if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
           return false;
         }
@@ -829,16 +1611,16 @@ var ChromeCdpBrowserController = class {
 
         const tag = el.tagName.toLowerCase();
         if (tag === 'input') {
-          const v = el.value;
-          if (v) return v.slice(0, 80);
-          const ph = el.getAttribute('placeholder');
-          if (ph) return ph.slice(0, 80);
+          const value = el.value;
+          if (value) return value.slice(0, 80);
+          const placeholder = el.getAttribute('placeholder');
+          if (placeholder) return placeholder.slice(0, 80);
           return el.type || 'text';
         }
 
         const directText = Array.from(el.childNodes)
-          .filter(n => n.nodeType === 3)
-          .map(n => n.textContent.trim())
+          .filter((node) => node.nodeType === 3)
+          .map((node) => node.textContent.trim())
           .filter(Boolean)
           .join(' ');
         if (directText) return directText.slice(0, 80);
@@ -861,48 +1643,95 @@ var ChromeCdpBrowserController = class {
         return ariaDisabled !== 'true';
       }
 
+      function rootEntries(root) {
+        if (!root) return [];
+        if (root.nodeType === Node.DOCUMENT_NODE) {
+          if (root.body) return [root.body];
+          if (root.documentElement) return [root.documentElement];
+          return [];
+        }
+        if (root.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+          return Array.from(root.children || []);
+        }
+        return [root];
+      }
+
       const results = [];
       let totalFound = 0;
 
-      for (const el of candidates) {
-        if (seen.has(el)) continue;
-        seen.add(el);
+      function maybeRecordElement(root, path, el) {
+        if (scopeElement && !isWithinComposedSubtree(scopeElement, el)) {
+          return;
+        }
+
+        if (!el.matches(candidateSelector)) {
+          return;
+        }
 
         const role = classifyRole(el);
-        if (roleFilter && !roleFilter.has(role)) continue;
+        if (roleFilter && !roleFilter.has(role)) return;
 
-        const vis = isVisible(el);
-        if (visibleOnly && !vis) continue;
+        const visible = isVisible(el);
+        if (visibleOnly && !visible) return;
 
-        totalFound++;
-        if (results.length >= limit) continue;
+        totalFound += 1;
+        if (results.length >= limit) return;
 
-        const primarySelector = buildSelector(el);
+        const selector = composeLocator(path, buildSelector(root, el));
         const entry = {
-          selector: primarySelector,
+          selector,
           role,
           tagName: el.tagName.toLowerCase(),
           text: getText(el),
           actions: getActions(role, el),
-          visible: vis,
+          visible,
           enabled: isEnabled(el),
         };
 
-        const fb = buildFallbackSelectors(el, primarySelector);
-        if (fb.length) entry.fallbackSelectors = fb;
+        const fallbacks = buildFallbackSelectors(root, path, el, selector);
+        if (fallbacks.length) entry.fallbackSelectors = fallbacks;
 
         if (role === 'link' && el.href) entry.href = el.href;
         if (role === 'input') entry.inputType = (el.type || 'text').toLowerCase();
-        const al = el.getAttribute('aria-label');
-        if (al) entry.ariaLabel = al;
-        const ph = el.getAttribute('placeholder');
-        if (ph) entry.placeholder = ph;
+        const ariaLabel = el.getAttribute('aria-label');
+        if (ariaLabel) entry.ariaLabel = ariaLabel;
+        const placeholder = el.getAttribute('placeholder');
+        if (placeholder) entry.placeholder = placeholder;
 
         results.push(entry);
       }
 
+      function walkRoot(root, path) {
+        const queue = rootEntries(root).slice();
+        while (queue.length) {
+          const current = queue.shift();
+          if (!current || current.nodeType !== 1) continue;
+
+          maybeRecordElement(root, path, current);
+
+          if (current.shadowRoot) {
+            walkRoot(current.shadowRoot, path.concat(buildSelector(root, current)));
+          }
+
+          if (current.tagName && current.tagName.toLowerCase() === 'iframe') {
+            try {
+              if (current.contentDocument) {
+                walkRoot(current.contentDocument, path.concat(buildSelector(root, current)));
+              }
+            } catch {
+              // ignore inaccessible frames
+            }
+          }
+
+          for (const child of Array.from(current.children)) {
+            queue.push(child);
+          }
+        }
+      }
+
+      walkRoot(document, []);
       return { elements: results, totalFound, truncated: totalFound > results.length };
-    })()`;
+`);
 		const emptyResult = {
 			elements: [],
 			totalFound: 0,
@@ -1152,17 +1981,29 @@ var MockBrowserController = class {
 	async getContent(cdpUrl, options) {
 		const page = this.pages.get(cdpUrl);
 		if (!page) throw new Error("mock page missing");
-		if (options.mode === "title") return {
-			mode: "title",
-			content: page.title
-		};
-		if (options.mode === "html") return {
-			mode: "html",
-			content: page.html
+		if (options.mode === "summary") return {
+			mode: "summary",
+			content: "",
+			structuredContent: {
+				mode: "summary",
+				url: page.url,
+				title: page.title,
+				headings: [page.title],
+				landmarks: [],
+				alerts: [],
+				frames: [],
+				primaryActions: [],
+				inputs: [],
+				totalInteractiveElements: 0,
+				truncatedInteractiveElements: false
+			}
 		};
+		const limited = applyContentLimit(options.mode === "title" ? page.title : options.mode === "html" ? page.html : page.text, options.maxChars);
 		return {
-			mode: "text",
-			content: page.text
+			mode: options.mode,
+			content: limited.content,
+			truncated: limited.truncated || void 0,
+			originalLength: limited.originalLength
 		};
 	}
 	async getInteractiveElements(_targetWsUrl, _options) {
@@ -1178,7 +2019,6 @@ var MockBrowserController = class {
 	terminate(_pid) {}
 	closeConnection(_targetWsUrl) {}
 };
-
 //#endregion
 //#region src/session/session-store.ts
 var SessionStore = class {
@@ -1267,7 +2107,6 @@ var SessionStore = class {
 		fs.writeFileSync(this.filePath, JSON.stringify(state, null, 2), "utf8");
 	}
 };
-
 //#endregion
 //#region src/session/session-manager.ts
 var SessionManager = class {
@@ -1640,7 +2479,6 @@ var SessionManager = class {
 		}
 	}
 };
-
 //#endregion
 //#region src/transport/control-api.ts
 var ControlApi = class {
@@ -1694,7 +2532,6 @@ var ControlApi = class {
 		return this.sessions.cleanupSessions(input);
 	}
 };
-
 //#endregion
 //#region src/lib/config.ts
 const DEFAULT_PORT = 43111;
@@ -1720,7 +2557,6 @@ function loadConfig(env = process.env) {
 		userAgent: env.AGENTIC_BROWSER_USER_AGENT || void 0
 	};
 }
-
 //#endregion
 //#region src/observability/logger.ts
 var Logger = class {
@@ -1752,23 +2588,32 @@ var Logger = class {
 		this.emit("error", message, context);
 	}
 };
-
 //#endregion
 //#region src/observability/event-store.ts
 const MAX_EVENTS_PER_SESSION = 500;
 var EventStore = class {
 	events = /* @__PURE__ */ new Map();
 	filePath;
+	bufferedLines = [];
+	flushTimer;
+	flushInFlight;
 	constructor(baseDir) {
 		fs.mkdirSync(baseDir, { recursive: true });
 		this.filePath = path.join(baseDir, "session-events.log");
+		process.once("beforeExit", this.flushSync);
+		process.once("exit", this.flushSync);
 	}
 	append(event) {
 		let existing = this.events.get(event.sessionId) ?? [];
 		existing.push(event);
 		if (existing.length > MAX_EVENTS_PER_SESSION) existing = existing.slice(-MAX_EVENTS_PER_SESSION);
 		this.events.set(event.sessionId, existing);
-		fs.appendFileSync(this.filePath, `${JSON.stringify(event)}\n`, "utf8");
+		this.bufferedLines.push(`${JSON.stringify(event)}\n`);
+		if (this.bufferedLines.length >= 20) {
+			this.flushSoon(0);
+			return;
+		}
+		this.flushSoon(25);
 	}
 	list(sessionId, limit = 100) {
 		const entries = this.events.get(sessionId) ?? [];
@@ -1777,8 +2622,37 @@ var EventStore = class {
 	clear(sessionId) {
 		this.events.delete(sessionId);
 	}
+	flushSoon(delayMs) {
+		if (this.flushInFlight) return this.flushInFlight;
+		if (this.flushTimer) return Promise.resolve();
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = void 0;
+			this.flushAsync();
+		}, delayMs);
+		this.flushTimer.unref();
+		return Promise.resolve();
+	}
+	async flushAsync() {
+		if (this.flushInFlight || this.bufferedLines.length === 0) return;
+		const chunk = this.bufferedLines.splice(0, this.bufferedLines.length).join("");
+		this.flushInFlight = fs.promises.appendFile(this.filePath, chunk, "utf8").catch(() => {}).finally(() => {
+			this.flushInFlight = void 0;
+			if (this.bufferedLines.length > 0) this.flushSoon(0);
+		});
+		await this.flushInFlight;
+	}
+	flushSync = () => {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = void 0;
+		}
+		if (this.bufferedLines.length === 0) return;
+		const chunk = this.bufferedLines.splice(0, this.bufferedLines.length).join("");
+		try {
+			fs.appendFileSync(this.filePath, chunk, "utf8");
+		} catch {}
+	};
 };
-
 //#endregion
 //#region src/auth/session-token.ts
 var SessionTokenService = class {
@@ -1806,7 +2680,6 @@ var SessionTokenService = class {
 		this.tokens.set(sessionId, token);
 	}
 };
-
 //#endregion
 //#region src/transport/ws-server.ts
 var AuthenticatedWsServer = class {
@@ -1841,7 +2714,6 @@ var AuthenticatedWsServer = class {
 		this.server = void 0;
 	}
 };
-
 //#endregion
 //#region src/memory/memory-index.ts
 function normalize(value) {
@@ -1902,11 +2774,10 @@ function scoreInsight(insight, normalizedIntent, normalizedDomain) {
 var MemoryIndex = class {
 	/** Domain → insights index, rebuilt lazily when insight list changes. */
 	domainIndex = /* @__PURE__ */ new Map();
-	indexedInsights = null;
-	indexedLength = 0;
-	/** Rebuild the domain index when the underlying array or its size changes. */
+	indexedRefs = [];
+	/** Rebuild the domain index when the insight object set changes. */
 	ensureIndex(insights) {
-		if (this.indexedInsights === insights && this.indexedLength === insights.length) return;
+		if (this.indexedRefs.length === insights.length && insights.every((insight, index) => this.indexedRefs[index] === insight)) return;
 		this.domainIndex.clear();
 		for (const insight of insights) {
 			const domain = normalize(insight.siteDomain);
@@ -1917,8 +2788,7 @@ var MemoryIndex = class {
 			}
 			bucket.push(insight);
 		}
-		this.indexedInsights = insights;
-		this.indexedLength = insights.length;
+		this.indexedRefs = insights.slice();
 	}
 	search(insights, input) {
 		const normalizedIntent = normalize(input.taskIntent);
@@ -1940,7 +2810,6 @@ var MemoryIndex = class {
 		return candidates.map((insight) => scoreInsight(insight, normalizedIntent, normalizedDomain)).filter((result) => result.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
 	}
 };
-
 //#endregion
 //#region src/memory/staleness-detector.ts
 const MAX_SUSPECT_STRIKES = 2;
@@ -1983,7 +2852,6 @@ function applySuccess(insight) {
 		updatedAt: now
 	};
 }
-
 //#endregion
 //#region src/memory/memory-schemas.ts
 const InsightFreshnessSchema = z.enum([
@@ -2036,7 +2904,6 @@ const TaskInsightSchema = z.object({
 	selectorAliases: z.array(SelectorAliasSchema).default([])
 });
 const MemoryStateSchema = z.object({ insights: z.array(TaskInsightSchema) });
-
 //#endregion
 //#region src/memory/task-insight-store.ts
 const EMPTY_STATE = { insights: [] };
@@ -2160,7 +3027,6 @@ var TaskInsightStore = class {
 		});
 	}
 };
-
 //#endregion
 //#region src/memory/memory-service.ts
 const SEARCH_CACHE_TTL_MS = 2e3;
@@ -2380,7 +3246,6 @@ var MemoryService = class {
 		return [...recipe, step].slice(-8);
 	}
 };
-
 //#endregion
 //#region src/cli/app.ts
 function createAppContext(env = process.env) {
@@ -2401,7 +3266,6 @@ function createAppContext(env = process.env) {
 		memoryService: new MemoryService(config.logDir)
 	};
 }
-
 //#endregion
 //#region src/cli/runtime.ts
 var AgenticBrowserCore = class {
@@ -2429,7 +3293,8 @@ var AgenticBrowserCore = class {
 	async getPageContent(input) {
 		return await this.api.getContent(input.sessionId, {
 			mode: input.mode,
-			selector: input.selector
+			selector: input.selector,
+			maxChars: input.maxChars
 		});
 	}
 	async getInteractiveElements(input) {
@@ -2475,6 +3340,5 @@ function createMockAgenticBrowserCore(env) {
 function createCliRuntime() {
 	return createAgenticBrowserCore();
 }
-
 //#endregion
-export { createMockAgenticBrowserCore as i, createAgenticBrowserCore as n, createCliRuntime as r, AgenticBrowserCore as t };
+export { createMockAgenticBrowserCore as i, createAgenticBrowserCore as n, createCliRuntime as r, AgenticBrowserCore as t };