An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
feat(actions): add navigation and element waiting
Shahriar22f6b1bff285
diff --git a/lib/actions/page/navigate.ts b/lib/actions/page/navigate.tsnew file mode 100644index 0000000..b64ddb1--- /dev/null+++ b/lib/actions/page/navigate.ts@@ -0,0 +1,63 @@+import { z } from 'zod';+import { ActionError, defineAction } from '../core';++const input = z.object({+ url: z.string().optional().describe('Absolute or relative URL to open (http/https only)'),+ action: z+ .enum(['back', 'forward', 'reload'])+ .optional()+ .describe('History navigation instead of opening a URL'),+});++export type NavigateInput = z.output<typeof input>;++export type Navigation =+ | { kind: 'url'; href: string }+ | { kind: 'history'; action: 'back' | 'forward' | 'reload' };++/**+ * Validate a navigate request. Shared so the in-page action and the background worker's+ * tab-level path agree on what is allowed; `base` resolves relative URLs and is only+ * available in the page, so callers without one must pass an absolute URL.+ */+export function resolveNavigation({ url, action }: NavigateInput, base?: string): Navigation {+ if (!url === !action) {+ throw new ActionError('Provide either "url" or "action"', 'INVALID_INPUT');+ }+ if (action) return { kind: 'history', action };++ let destination: URL;+ try {+ destination = new URL(url!, base);+ } catch {+ throw new ActionError(+ base ? `Invalid URL: "${url}"` : `Invalid URL: "${url}" — pass an absolute http(s) URL`,+ 'INVALID_INPUT',+ );+ }+ if (destination.protocol !== 'http:' && destination.protocol !== 'https:') {+ throw new ActionError(+ `Only http(s) URLs are supported, got "${destination.protocol}"`,+ 'UNSUPPORTED',+ );+ }+ return { kind: 'url', href: destination.href };+}++export const navigate = defineAction({+ name: 'page.navigate',+ description: 'Navigate the current tab to a URL, or go back, forward, or reload in its history.',+ input,+ execute(request) {+ const plan = resolveNavigation(request, location.href);+ if (plan.kind === 'url') {+ // The page unloads on navigation, so the caller may never receive this response.+ location.assign(plan.href);+ return { navigatingTo: plan.href };+ }+ if (plan.action === 'back') history.back();+ else if (plan.action === 'forward') history.forward();+ else location.reload();+ return { performed: plan.action };+ },+});diff --git a/lib/actions/page/wait-for-element.ts b/lib/actions/page/wait-for-element.tsnew file mode 100644index 0000000..f4e795d--- /dev/null+++ b/lib/actions/page/wait-for-element.ts@@ -0,0 +1,76 @@+import { z } from 'zod';+import { ActionError, defineAction } from '../core';+import { describeElement, isVisible, resolveTarget, targetSchema } from './dom';++export const waitForElement = defineAction({+ name: 'page.waitForElement',+ description: 'Wait until an element reaches a state: attached, visible, hidden, or detached.',+ input: z.object({+ target: targetSchema.describe('Element to wait for'),+ state: z+ .enum(['attached', 'visible', 'hidden', 'detached'])+ .default('visible')+ .describe('State to wait for: present in the DOM, present and visible, invisible or absent, or absent'),+ timeoutMs: z+ .number()+ .int()+ .positive()+ .max(30000)+ .default(5000)+ .describe('Give up after this many milliseconds'),+ }),+ async execute({ target, state, timeoutMs }) {+ const find = (): HTMLElement | null => {+ try {+ // Keep hidden matches so 'attached'/'hidden'/'detached' can observe them; judge visibility below.+ return resolveTarget(target, { includeHidden: true });+ } catch (error) {+ if (error instanceof ActionError && error.code === 'INVALID_TARGET') throw error;+ return null;+ }+ };+ const satisfied = (el: HTMLElement | null): boolean =>+ ({+ attached: !!el,+ visible: !!el && isVisible(el),+ hidden: !el || !isVisible(el),+ detached: !el,+ })[state];+ const start = performance.now();+ let element = find();+ if (satisfied(element)) {+ return { state, elapsedMs: 0, element: element ? describeElement(element) : undefined };+ }+ await new Promise<void>((resolve, reject) => {+ const check = () => {+ element = find();+ if (satisfied(element)) {+ cleanup();+ resolve();+ }+ };+ const observer = new MutationObserver(check);+ observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true });+ const interval = setInterval(check, 250);+ const timer = setTimeout(() => {+ cleanup();+ reject(+ new ActionError(+ `Timed out after ${timeoutMs}ms waiting for element to be ${state}`,+ 'TIMEOUT',+ ),+ );+ }, timeoutMs);+ const cleanup = () => {+ observer.disconnect();+ clearInterval(interval);+ clearTimeout(timer);+ };+ });+ return {+ state,+ elapsedMs: Math.round(performance.now() - start),+ element: element ? describeElement(element) : undefined,+ };+ },+});