Skip to content

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.

feat(actions): add navigation and element waiting

Shahriar22f6b1bff285
diff --git a/lib/actions/page/navigate.ts b/lib/actions/page/navigate.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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,
+ };
+ },
+});