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
import type { LensCommand } from '@/lib/actions/page/lens';
export const PHONE_PORT = 'browsentic/phone';
/** `Page.screencastFrame`'s metadata: the phone's visual viewport when the frame was taken. */
export interface FrameMetadata {
offsetTop: number;
pageScaleFactor: number;
deviceWidth: number;
deviceHeight: number;
scrollOffsetX: number;
scrollOffsetY: number;
}
export type TouchType = 'touchStart' | 'touchMove' | 'touchEnd' | 'touchCancel';
export const MIRROR_KEYS = ['Enter', 'Backspace', 'Delete', 'Tab', 'Escape', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End'] as const;
export type MirrorKey = (typeof MIRROR_KEYS)[number];
export const isMirrorKey = (key: string): key is MirrorKey => (MIRROR_KEYS as readonly string[]).includes(key);
type KeyPress = Pick<KeyboardEvent, 'key' | 'metaKey' | 'ctrlKey' | 'altKey' | 'getModifierState'>;
/**
* The character a key press types, or undefined for a shortcut. AltGr reads as Ctrl+Alt on Windows,
* and Option alone types on a Mac, so both type: that is how `@`, `€` or `{` come on many layouts.
*/
export function typedText(press: KeyPress, mac: boolean): string | undefined {
if (press.key.length !== 1 || press.metaKey) return undefined;
if (press.getModifierState('AltGraph') || press.ctrlKey === press.altKey) return press.key;
return mac && press.altKey ? press.key : undefined;
}
export type MirrorCommand =
| { op: 'watch' }
| { op: 'unwatch' }
| { op: 'restart' }
| { op: 'ack'; frame: number }
| { op: 'touch'; type: TouchType; x: number; y: number }
| { op: 'wheel'; x: number; y: number; deltaX: number; deltaY: number }
| { op: 'text'; text: string }
| { op: 'key'; key: MirrorKey }
/** While A-Eye waits on the phone; points are where a touch would land. */
| { op: 'lens'; lens: LensCommand }
| { op: 'go'; url: string }
| { op: 'back' }
| { op: 'forward' }
| { op: 'reload' }
| { op: 'switchTab'; targetId: string }
| { op: 'newTab' }
| { op: 'closeTab'; targetId: string };
export interface PageState {
targetId: string;
url: string;
title: string;
canGoBack: boolean;
canGoForward: boolean;
}
export type MirrorMessage =
| { kind: 'frame'; data: string; metadata: FrameMetadata; frame: number }
| ({ kind: 'page' } & PageState)
| { kind: 'lens'; active: boolean }
| { kind: 'error'; message: string };
/**
* Where a point on the drawn frame lands on the phone, in the CSS px a touch event takes. The frame
* is the visual viewport alone, so the phone's own top bar plays no part (spike Q8).
*/
export function touchPoint(
fraction: { x: number; y: number },
metadata: Pick<FrameMetadata, 'deviceWidth' | 'pageScaleFactor'>,
image: { width: number; height: number },
): { x: number; y: number } {
const width = metadata.deviceWidth / (metadata.pageScaleFactor || 1);
return { x: fraction.x * width, y: fraction.y * width * (image.height / image.width) };
}
/** Key events that edit only with `windowsVirtualKeyCode`, and an Enter that submits only as `keyDown` with its `text` (spike Q7). */
const KEYS: Record<MirrorKey, { code: string; keyCode: number; text?: string }> = {
Enter: { code: 'Enter', keyCode: 13, text: '\r' },
Backspace: { code: 'Backspace', keyCode: 8 },
Delete: { code: 'Delete', keyCode: 46 },
Tab: { code: 'Tab', keyCode: 9 },
Escape: { code: 'Escape', keyCode: 27 },
ArrowLeft: { code: 'ArrowLeft', keyCode: 37 },
ArrowRight: { code: 'ArrowRight', keyCode: 39 },
ArrowUp: { code: 'ArrowUp', keyCode: 38 },
ArrowDown: { code: 'ArrowDown', keyCode: 40 },
Home: { code: 'Home', keyCode: 36 },
End: { code: 'End', keyCode: 35 },
};
export function keyEvents(key: MirrorKey): Record<string, unknown>[] {
const { code, keyCode, text } = KEYS[key];
const base = { key, code, windowsVirtualKeyCode: keyCode, nativeVirtualKeyCode: keyCode };
return [{ type: text ? 'keyDown' : 'rawKeyDown', ...base, ...(text ? { text, unmodifiedText: text } : {}) }, { type: 'keyUp', ...base }];
}
/** What the mirror's address bar was given, as a URL: a bare host gets https://, anything else is searched for. */
export function addressOf(typed: string): string {
const text = typed.trim();
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text) || /^(about|chrome|data):/i.test(text)) return text;
if (/^[^\s/]+\.[^\s/]{2,}(\/\S*)?$/.test(text) || /^localhost(:\d+)?(\/\S*)?$/.test(text)) return `https://${text}`;
return `https://www.google.com/search?q=${encodeURIComponent(text)}`;
}