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(android): every phone tool works on the phone: page-side actions run unchanged in an isolated world there, clicks and drags are real touches, typing and keys are real input, scrolling is wheel steps, and screenshots come from the phone at CSS size
Shahriard52a529e90cc
diff --git a/src/daemon/android/relay.test.ts b/src/daemon/android/relay.test.tsindex f04e945..39daa51 100644--- a/src/daemon/android/relay.test.ts+++ b/src/daemon/android/relay.test.ts@@ -200,6 +200,13 @@ describe('commands and events', () => {expect(chrome.commands.at(-1)).toEqual({ method: 'Runtime.evaluate', params: { expression: 'document.title' }, sessionId: 'S1' });});+ test('a command can ask to wait longer than the default, for a page-side wait', async () => {+ const asked = relay.command(owner, { t: 'cdp', id: 'f7', serial: SERIAL, method: 'Hang.forever', timeoutMs: 400 });+ await new Promise((resolve) => setTimeout(resolve, 200));+ expect(await Promise.race([asked, Promise.resolve('still waiting')])).toBe('still waiting');+ expect(await asked).toMatchObject({ ok: false, error: { code: 'TIMEOUT' } });+ });+test('Chrome\'s refusal is CDP_ERROR in its own words, and silence is TIMEOUT', async () => {expect(await relay.command(owner, { t: 'cdp', id: 'f2', serial: SERIAL, method: 'Nope.nope' })).toEqual({ok: false,diff --git a/src/daemon/android/relay.ts b/src/daemon/android/relay.tsindex 05c8fc8..87bd4cc 100644--- a/src/daemon/android/relay.ts+++ b/src/daemon/android/relay.ts@@ -32,6 +32,8 @@ export interface RelayDeps {const DEVTOOLS_SOCKET = 'localabstract:chrome_devtools_remote';const TIMEOUTS = { connect: 5_000, command: 15_000, slow: 30_000 };+/** The longest a caller may ask one command to wait: a page-side wait or a long typing run awaited in the page. */+const LONGEST_COMMAND_MS = 180_000;const SLOW_COMMANDS = new Set(['Page.captureScreenshot', 'Page.navigate']);const FRAME_BACKLOG_BYTES = 4 * 1024 * 1024;const MAX_MESSAGE_BYTES = 256 * 1024 * 1024;@@ -63,12 +65,12 @@ export function startRelay({ server, state, onSession, host = '127.0.0.1', timeoonSession(current && { serial: current.serial, since: current.since });};- function call(session: Session, method: string, params?: Record<string, unknown>, sessionId?: string): Promise<CdpResult> {+ function call(session: Session, method: string, params?: Record<string, unknown>, sessionId?: string, asked?: number): Promise<CdpResult> {if (sessions.get(session.serial) !== session || session.socket.readyState !== WebSocket.OPEN) {return Promise.resolve(failure('PHONE_GONE', 'The phone disconnected.'));}const id = session.nextId++;- const timeoutMs = SLOW_COMMANDS.has(method) ? timeouts.slow : timeouts.command;+ const timeoutMs = asked ? Math.min(asked, LONGEST_COMMAND_MS) : SLOW_COMMANDS.has(method) ? timeouts.slow : timeouts.command;return new Promise((resolve) => {const timer = setTimeout(() => {session.calls.delete(id);@@ -199,12 +201,12 @@ export function startRelay({ server, state, onSession, host = '127.0.0.1', timeoreturn {open,- async command(owner, { serial, method, params, sessionId }) {+ async command(owner, { serial, method, params, sessionId, timeoutMs }) {const session = sessions.get(serial);if (!session) return failure('PHONE_GONE', 'No phone session is open. Switch Android on again.');if (session.owner !== owner) return failure('NOT_OWNER', 'Another browser is driving this phone.');const started = Date.now();- const result = await call(session, method, params, sessionId);+ const result = await call(session, method, params, sessionId, timeoutMs);if (!isChatter(method, params)) log(`phone ${serial} ${method} ${result.ok ? 'ok' : result.error.code} in ${Date.now() - started} ms`);return result;},diff --git a/src/daemon/test/protocol-window.test.ts b/src/daemon/test/protocol-window.test.tsindex 3d3fb07..8e57a24 100644--- a/src/daemon/test/protocol-window.test.ts+++ b/src/daemon/test/protocol-window.test.ts@@ -85,8 +85,9 @@ describe('the protocol window', () => {});async function eventually(done: () => boolean): Promise<void> {- for (let tries = 0; !done(); tries++) {- if (tries > 400) throw new Error('timed out waiting');+ const deadline = Date.now() + 10_000;+ while (!done()) {+ if (Date.now() > deadline) throw new Error('timed out waiting');await new Promise((resolve) => setTimeout(resolve, 5));}}diff --git a/src/extension/entrypoints/phone-page.ts b/src/extension/entrypoints/phone-page.tsnew file mode 100644index 0000000..9e7e007--- /dev/null+++ b/src/extension/entrypoints/phone-page.ts@@ -0,0 +1,3 @@+import { installPhoneApi } from '@/lib/phone/page-api';++export default defineUnlistedScript(() => installPhoneApi());diff --git a/src/lib/actions/protocol.ts b/src/lib/actions/protocol.tsindex 44e2117..c49a1c1 100644--- a/src/lib/actions/protocol.ts+++ b/src/lib/actions/protocol.ts@@ -291,7 +291,7 @@ export type SocketFrame =| { t: 'phoneOpened'; id: string; result: ActionResult<PhoneOpened> }| { t: 'phoneClose'; id: string; serial: string }| { t: 'phoneLaunch'; id: string; serial: string; url?: string }- | { t: 'cdp'; id: string; serial: string; method: string; params?: Record<string, unknown>; sessionId?: string }+ | { t: 'cdp'; id: string; serial: string; method: string; params?: Record<string, unknown>; sessionId?: string; timeoutMs?: number }| { t: 'cdpResult'; id: string; result: ActionResult<Record<string, unknown>> }| { t: 'cdpEvent'; serial: string; method: string; params: Record<string, unknown>; sessionId?: string }| { t: 'phoneClosed'; serial: string; reason: PhoneClosedReason };diff --git a/src/lib/bridge/invoke.ts b/src/lib/bridge/invoke.tsindex e18085f..38a8a33 100644--- a/src/lib/bridge/invoke.ts+++ b/src/lib/bridge/invoke.ts@@ -64,6 +64,7 @@ import { dragInTab, trustedClickInTab } from '@/lib/bridge/trusted-input';import { closeOpenTab, openNewTab, switchToTab, watchForLoad, type TabRef } from '@/lib/bridge/tabs';import { adoptSubtab, sessionForRun, sessionForTab, setCurrentTab, type TabSession } from '@/lib/bridge/tab-sessions';import { invokeOnPhone, phoneRoute } from '@/lib/bridge/phone-invoke';+import { HOST_SIDE } from '@/lib/phone/features';/*** The sanitizer's client-side half, wrapped around every action the harness runs.@@ -79,7 +80,7 @@ export async function invokeForHarness(tabId?: number,runId?: string,): Promise<ActionResult> {- const phone = await phoneRoute(tabId, runId);+ const phone = HOST_SIDE.has(action) ? null : await phoneRoute(tabId, runId);if (phone) return invokeOnPhone(action, input, phone);const refused = await guardTarget(action, input, tabId, runId);diff --git a/src/lib/bridge/phone-backend.test.ts b/src/lib/bridge/phone-backend.test.tsnew file mode 100644index 0000000..a6a4bf0--- /dev/null+++ b/src/lib/bridge/phone-backend.test.ts@@ -0,0 +1,128 @@+import { beforeEach, describe, expect, test, vi } from 'vitest';+import { fakeBrowser } from 'wxt/testing';+import { failure, success, type ActionResult } from '@/lib/actions/protocol';+import type { PhoneSession } from './phone';++const TARGET = 'A'.repeat(32);++const phone = vi.hoisted(() => ({+ sent: [] as { method: string; params?: Record<string, unknown> }[],+ contexts: 0,+ answer: (_expression: string): unknown => ({ ok: true, data: {} }),+ goneOnce: false,+ viewport: { offsetX: 0, offsetY: 50, clientWidth: 411, clientHeight: 675 },+}));++vi.mock('./socket', () => ({+ DAEMON_STATE_KEY: 'browsentic/daemon',+ sendCdp: async (_serial: string, method: string, params?: Record<string, unknown>) => {+ phone.sent.push({ method, params });+ if (method === 'Page.getFrameTree') return success({ frameTree: { frame: { id: 'TOP' } } });+ if (method === 'Page.createIsolatedWorld') return success({ executionContextId: ++phone.contexts });+ if (method === 'Page.getLayoutMetrics') return success({ cssVisualViewport: phone.viewport });+ if (method === 'Runtime.evaluate' && String(params?.expression).startsWith('__browsenticPhone.dispatch')) {+ if (phone.goneOnce) {+ phone.goneOnce = false;+ return failure('CDP_ERROR', 'Cannot find context with specified id');+ }+ return success({ result: { value: phone.answer(String(params?.expression)) } });+ }+ if (method === 'Runtime.evaluate' && String(params?.expression).includes('scrollY')) return success({ result: { value: { scrollX: 0, scrollY: 574 } } });+ return success({});+ },+ onCdpEvent: () => undefined,+ onPhoneClosed: () => undefined,+ onDaemonClosed: () => undefined,+}));++vi.mock('./phone-mirror', () => ({ attachedSession: async () => 'session-1' }));++const { pageSideOnPhone, shotClip } = await import('./phone-backend');++const SESSION: PhoneSession = {+ serial: 'emulator-5554',+ mirrorTabId: 9,+ windowId: 1,+ openedAt: 0,+ activeTargetId: TARGET,+ targets: [{ targetId: TARGET, url: 'http://localhost:8080/', title: 'Spike page' }],+};++const methods = () => phone.sent.map(({ method }) => method);+const input = (type: string) => phone.sent.filter(({ method, params }) => method === 'Input.dispatchTouchEvent' && params?.type === type);++beforeEach(() => {+ fakeBrowser.reset();+ phone.sent.length = 0;+ phone.goneOnce = false;+ phone.viewport = { offsetX: 0, offsetY: 50, clientWidth: 411, clientHeight: 675 };+ phone.answer = () => ({ ok: true, data: {} });+ vi.stubGlobal('fetch', async () => new Response('/* the bundle */'));+});++describe('page-side tools on the phone', () => {+ test('run in an isolated world that is made, and given the bundle, once', async () => {+ phone.answer = () => ({ ok: true, data: { title: 'Spike page' } });+ const first = await pageSideOnPhone('page.getPageInfo', {}, SESSION);+ await pageSideOnPhone('page.extractText', {}, SESSION);+ expect(first).toEqual({ ok: true, data: { title: 'Spike page' } });+ expect(methods().filter((method) => method === 'Page.createIsolatedWorld')).toHaveLength(1);+ expect(phone.sent.filter(({ params }) => params?.expression === '/* the bundle */')).toHaveLength(1);+ });++ test('a navigation that killed the world makes it again and retries once', async () => {+ await pageSideOnPhone('page.getPageInfo', {}, SESSION);+ const before = methods().filter((method) => method === 'Page.createIsolatedWorld').length;+ phone.goneOnce = true;+ expect((await pageSideOnPhone('page.getPageInfo', {}, SESSION)).ok).toBe(true);+ expect(methods().filter((method) => method === 'Page.createIsolatedWorld').length - before).toBe(1);+ });+});++describe('touch on the phone', () => {+ test('a click is a tap at the page’s point less the visual viewport’s offset, reported like a click', async () => {+ phone.answer = () => ({ ok: true, data: { tag: 'a', text: 'Go to second', point: { x: 100, y: 200 }, from: { x: 90, y: 190 }, button: 'left', submits: false } });+ const clicked = (await pageSideOnPhone('page.clickElement', { target: { selector: '#link' } }, SESSION)) as ActionResult<Record<string, unknown>>;+ expect(clicked).toEqual({ ok: true, data: { tag: 'a', text: 'Go to second', submits: false } });+ expect(input('touchStart')[0].params?.touchPoints).toEqual([{ x: 100, y: 150 }]);+ expect(input('touchEnd')[0].params?.touchPoints).toEqual([]);+ });++ test('a point off the visible screen is not touched, and says why', async () => {+ phone.answer = () => ({ ok: true, data: { point: { x: 100, y: 2000 } } });+ expect(await pageSideOnPhone('page.clickElement', { target: { selector: '#far' } }, SESSION)).toMatchObject({ ok: false, error: { code: 'TAP_MISSED' } });+ expect(input('touchStart')).toEqual([]);+ });++ test('scrolling a screen down is wheel steps at the middle of the screen, adding up to 85% of it', async () => {+ const scrolled = await pageSideOnPhone('page.scrollTo', { direction: 'down' }, SESSION);+ const wheels = phone.sent.filter(({ params }) => params?.type === 'mouseWheel');+ expect(wheels.reduce((sum, { params }) => sum + Number(params?.deltaY), 0)).toBe(Math.round(675 * 0.85));+ expect(wheels[0].params).toMatchObject({ x: 205.5, y: 337.5 });+ expect(scrolled).toEqual({ ok: true, data: { direction: 'down', scrollX: 0, scrollY: 574 } });+ });++ test('typing focuses the field in the page, selects what it held, and inserts the text', async () => {+ phone.answer = () => ({ ok: true, data: { tag: 'input' } });+ await pageSideOnPhone('page.typeText', { target: { selector: '#inp' }, text: 'hello\nworld' }, SESSION);+ const typed = phone.sent.filter(({ method }) => method === 'Input.insertText' || method === 'Input.dispatchKeyEvent').map(({ params }) => params?.text ?? params?.type);+ expect(typed).toEqual(['hello', '\r', 'keyUp', 'world']);+ expect(phone.sent.some(({ params }) => String(params?.expression).includes('page.focusInput'))).toBe(true);+ expect(phone.sent.some(({ params }) => String(params?.expression).includes('select()'))).toBe(true);+ });+});++describe('a screenshot on the phone', () => {+ const plan = { mode: 'viewport' as const, dpr: 2.625, viewport: { w: 411, h: 675 }, region: { x: 0, y: 300, w: 411, h: 675 }, format: 'jpeg' as const, maxLongSide: 675 };++ test('clips in CSS px and scales against device pixels, so one image pixel is one CSS pixel', () => {+ expect(shotClip(plan)).toEqual({ clip: { x: 0, y: 300, width: 411, height: 675, scale: 1 / 2.625 }, width: 411, height: 675, truncated: false });+ });++ test('a long page is cut at eight screens and fitted to the longest side asked for', () => {+ const shot = shotClip({ ...plan, mode: 'fullPage', region: { x: 0, y: 0, w: 411, h: 11_000 }, maxLongSide: 1600 });+ expect(shot.truncated).toBe(true);+ expect(shot.clip.height).toBe(5400);+ expect([shot.width, shot.height]).toEqual([Math.round(411 * (1600 / 5400)), 1600]);+ });+});diff --git a/src/lib/bridge/phone-backend.ts b/src/lib/bridge/phone-backend.tsnew file mode 100644index 0000000..4ad2844--- /dev/null+++ b/src/lib/bridge/phone-backend.ts@@ -0,0 +1,333 @@+import { browser } from 'wxt/browser';+import { z } from 'zod';+import { pressKey } from '@/lib/actions/page/press-key';+import { scrollTo } from '@/lib/actions/page/scroll-to';+import { switchFrame } from '@/lib/actions/page/switch-frame';+import { typeText } from '@/lib/actions/page/type-text';+import { failure, success, type ActionResult } from '@/lib/actions/protocol';+import { PHONE_API } from '@/lib/phone/page-api';+import { drag, keyPress, onScreen, tap, typing, wheel, type InputStep, type Point, type Viewport } from '@/lib/phone/touch';+import { currentTarget, type PhoneSession } from './phone';+import { attachedSession } from './phone-mirror';+import { sendCdp } from './socket';++const BUNDLE = '/phone-page.js';+const WORLD = 'browsentic';+const CALL_TIMEOUT_MS = 20_000;+const LOAD_TIMEOUT_MS = 15_000;+const LOAD_POLL_MS = 150;+const SETTLE_MS = 300;+const SCROLL_PAGE = 0.85;+const MAX_SHOT_SCREENS = 8;+const GONE = 'The phone disconnected. Reconnect it and switch Android on again.';++type CdpResult = ActionResult<Record<string, unknown>>;++interface Here {+ phone: PhoneSession;+ targetId: string;+ url: string;+ sessionId: string;+ cdp(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<CdpResult>;+}++let bundle: Promise<string> | null = null;+const worlds = new Map<string, number>();+const topFrames = new Map<string, string>();+const framePaths = new Map<string, { url: string; frames: string[] }>();++const loadBundle = (): Promise<string> =>+ (bundle ??= fetch((browser.runtime.getURL as (path: string) => string)(BUNDLE)).then((response) => {+ if (!response.ok) throw new Error(`the phone page bundle is missing (${response.status})`);+ return response.text();+ }));++const pause = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));++export async function hereOn(phone: PhoneSession): Promise<Here | null> {+ const target = currentTarget(phone);+ const sessionId = target && (await attachedSession(phone.serial, target.targetId));+ if (!target || !sessionId) return null;+ return {+ phone,+ targetId: target.targetId,+ url: target.url,+ sessionId,+ cdp: (method, params, timeoutMs) => sendCdp(phone.serial, method, params, sessionId, timeoutMs),+ };+}++/** Waits for the phone tab's document to finish loading, read from its main world, which outlives no navigation but needs none. */+export async function waitForLoad(here: Here): Promise<{ url: string; title: string; loaded: boolean }> {+ const deadline = Date.now() + LOAD_TIMEOUT_MS;+ let seen = { url: here.url, title: '', readyState: '' };+ while (Date.now() < deadline) {+ await pause(LOAD_POLL_MS);+ const state = await here.cdp('Runtime.evaluate', {+ expression: 'JSON.stringify({ url: location.href, title: document.title, readyState: document.readyState })',+ returnByValue: true,+ });+ if (!state.ok) continue;+ seen = JSON.parse(String((state.data.result as { value?: unknown }).value ?? '{}'));+ if (seen.readyState === 'complete' && seen.url !== 'about:blank') return { url: seen.url, title: seen.title, loaded: true };+ }+ return { url: seen.url, title: seen.title, loaded: false };+}++async function topFrame(here: Here): Promise<string> {+ const known = topFrames.get(here.sessionId);+ if (known) return known;+ const tree = await here.cdp('Page.getFrameTree');+ const id = tree.ok ? String((tree.data.frameTree as { frame: { id: string } }).frame.id) : here.targetId;+ topFrames.set(here.sessionId, id);+ return id;+}++/** The frame a page action runs in: the one `switchFrame` entered, until the tab's address changes. */+async function focusedFrame(here: Here): Promise<{ frameId: string; path: string[] }> {+ const held = framePaths.get(here.targetId);+ const path = held && held.url === here.url ? held.frames : [];+ return { frameId: path.at(-1) ?? (await topFrame(here)), path };+}++/**+ * An isolated world per frame, with the action bundle evaluated in it on first use. A world dies+ * with its document, so a call that finds its context gone makes the world again and retries once.+ */+async function world(here: Here, frameId: string, fresh: boolean): Promise<number | null> {+ const key = `${here.sessionId}:${frameId}`;+ const known = worlds.get(key);+ if (known !== undefined && !fresh) return known;+ worlds.delete(key);+ const created = await here.cdp('Page.createIsolatedWorld', { frameId, worldName: WORLD });+ if (!created.ok) return null;+ const contextId = Number(created.data.executionContextId);+ const loaded = await here.cdp('Runtime.evaluate', { expression: await loadBundle(), contextId });+ if (!loaded.ok || loaded.data.exceptionDetails) return null;+ worlds.set(key, contextId);+ return contextId;+}++const contextGone = (message: string) => /Cannot find context|context was destroyed|Execution context/i.test(message);++async function evaluateIn(here: Here, frameId: string, expression: string, options: { timeoutMs?: number; byValue?: boolean } = {}): Promise<ActionResult<unknown>> {+ const { timeoutMs = CALL_TIMEOUT_MS, byValue = true } = options;+ for (const fresh of [false, true]) {+ const contextId = await world(here, frameId, fresh);+ if (contextId === null) return failure('PHONE_PAGE_UNREACHABLE', 'Browsentic could not reach this page on the phone. It may still be loading; try again.');+ const evaluated = await here.cdp('Runtime.evaluate', { expression, contextId, awaitPromise: true, returnByValue: byValue }, timeoutMs);+ if (!evaluated.ok) {+ if (!fresh && contextGone(evaluated.error.message)) continue;+ return evaluated;+ }+ const thrown = evaluated.data.exceptionDetails as { text?: string; exception?: { description?: string } } | undefined;+ if (thrown) {+ const message = thrown.exception?.description?.split('\n')[0] ?? thrown.text ?? 'The page threw';+ if (!fresh && contextGone(message)) continue;+ return failure('ACTION_FAILED', message);+ }+ const result = evaluated.data.result as { value?: unknown } | undefined;+ return success(byValue ? result?.value : result);+ }+ return failure('PHONE_PAGE_UNREACHABLE', 'The page on the phone kept changing under Browsentic. Try again once it has loaded.');+}++const declaredWait = (input: unknown): number | undefined => {+ const declared = (input as { timeoutMs?: unknown } | undefined)?.timeoutMs;+ return typeof declared === 'number' && declared > 0 ? declared + 5_000 : undefined;+};++/** The action's own page-side code, unchanged, run in the phone page's isolated world. */+async function inPage(here: Here, action: string, input: unknown, frameId?: string): Promise<ActionResult> {+ const frame = frameId ?? (await focusedFrame(here)).frameId;+ const ran = await evaluateIn(here, frame, `${PHONE_API}.dispatch(${JSON.stringify(action)}, ${JSON.stringify(input ?? {})})`, { timeoutMs: declaredWait(input) });+ return ran.ok ? (ran.data as ActionResult) : ran;+}++async function visualViewport(here: Here): Promise<Viewport | null> {+ const metrics = await here.cdp('Page.getLayoutMetrics');+ const visual = metrics.ok ? (metrics.data.cssVisualViewport as { offsetX: number; offsetY: number; clientWidth: number; clientHeight: number }) : null;+ return visual && { offsetX: visual.offsetX, offsetY: visual.offsetY, width: visual.clientWidth, height: visual.clientHeight };+}++/** A frame's page point in the top document: the frame's content box is where its own coordinates start. */+async function inTopDocument(here: Here, point: Point): Promise<Point> {+ const { path } = await focusedFrame(here);+ const innermost = path.at(-1);+ if (!innermost) return point;+ await here.cdp('DOM.getDocument', { depth: 0 });+ const owner = await here.cdp('DOM.getFrameOwner', { frameId: innermost });+ const box = owner.ok ? await here.cdp('DOM.getBoxModel', { backendNodeId: owner.data.backendNodeId }) : null;+ const content = box?.ok ? ((box.data.model as { content: number[] }).content ?? []) : [];+ return { x: point.x + (content[0] ?? 0), y: point.y + (content[1] ?? 0) };+}++async function screenPoint(here: Here, point: Point): Promise<Point | null> {+ const viewport = await visualViewport(here);+ return viewport && onScreen(await inTopDocument(here, point), viewport);+}++async function play(here: Here, steps: InputStep[]): Promise<CdpResult | null> {+ for (const step of steps) {+ const sent = await here.cdp(step.method, step.params);+ if (!sent.ok) return sent;+ if (step.waitMs) await pause(step.waitMs);+ }+ return null;+}++const missed = () => failure('TAP_MISSED', 'That point is outside the visible part of the phone screen, so nothing was touched. Scroll it into view first.');++const PLAN_ONLY = ['point', 'from', 'button', 'clickCount', 'modifiers', 'moveSteps', 'hoverMs', 'holdMs'];++/** A click on the phone is a real tap where the page says the element's centre is: the page sees touch, pointer and click events, all trusted. */+async function tapOn(here: Here, input: Record<string, unknown>, asClick: boolean): Promise<ActionResult> {+ const planned = await inPage(here, 'page.trustedClick', asClick ? { target: input.target, scrollIntoView: input.scrollIntoView ?? true } : input);+ if (!planned.ok) return planned;+ const plan = planned.data as Record<string, unknown> & { point: Point };+ const at = await screenPoint(here, plan.point);+ if (!at) return missed();+ const failed = await play(here, tap(at));+ if (failed) return failed;+ const described = Object.fromEntries(Object.entries(plan).filter(([key]) => !PLAN_ONLY.includes(key)));+ return success(asClick ? described : { ...described, tapped: at });+}++async function dragOn(here: Here, input: Record<string, unknown>): Promise<ActionResult> {+ const planned = await inPage(here, 'page.dragElement', { ...input, trusted: true });+ if (!planned.ok) return planned;+ const plan = planned.data as { grip: Point; drop: Point; steps: number; from?: unknown; to?: unknown; mechanism: string };+ const [from, to] = await Promise.all([screenPoint(here, plan.grip), screenPoint(here, plan.drop)]);+ if (!from || !to) return missed();+ const failed = await play(here, drag(from, to, plan.steps));+ return failed ?? success({ from: plan.from, to: plan.to, mechanism: plan.mechanism, trusted: true, gesture: 'touch' });+}++const SELECT_FOCUSED = `(() => { const el = document.activeElement; if (el && typeof el.select === 'function') el.select(); else if (el && el.isContentEditable) document.execCommand('selectAll'); return !!el; })()`;++/** Typing focuses the field in the page, which keeps the phone's own keyboard closed, then types with real input events. */+async function typeOn(here: Here, input: unknown): Promise<ActionResult> {+ const parsed = typeText.input.safeParse(input ?? {});+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));+ const { target, text, clear } = parsed.data;+ const focused = target ? await inPage(here, 'page.focusInput', { target }) : null;+ if (focused && !focused.ok) return focused;+ const { frameId } = await focusedFrame(here);+ if (clear) await evaluateIn(here, frameId, SELECT_FOCUSED);+ const failed = await play(here, typing(text));+ return failed ?? success({ ...(focused?.ok ? (focused.data as object) : {}), typed: text.length, cleared: clear });+}++async function pressOn(here: Here, input: unknown): Promise<ActionResult> {+ const parsed = pressKey.input.safeParse(input ?? {});+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));+ const { key, modifiers, target } = parsed.data;+ if (target) {+ const focused = await inPage(here, 'page.focusInput', { target });+ if (!focused.ok && focused.error.code !== 'INVALID_TARGET') return focused;+ }+ const failed = await play(here, keyPress(key, modifiers));+ return failed ?? success({ pressed: key, modifiers });+}++/** Scrolling by a screen is wheel steps at the middle of the screen, so lazy lists load as they would under a finger. Everything else is the page's own scroll. */+async function scrollOn(here: Here, input: unknown): Promise<ActionResult> {+ const parsed = scrollTo.input.safeParse(input ?? {});+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));+ const { direction } = parsed.data;+ if (direction !== 'up' && direction !== 'down') return inPage(here, scrollTo.name, { ...parsed.data, behavior: 'instant' });+ const viewport = await visualViewport(here);+ if (!viewport) return failure('PHONE_GONE', GONE);+ const middle = { x: viewport.width / 2, y: viewport.height / 2 };+ const failed = await play(here, wheel(middle, (direction === 'down' ? 1 : -1) * Math.round(viewport.height * SCROLL_PAGE)));+ if (failed) return failed;+ const position = await evaluateIn(here, await topFrame(here), '({ scrollX: Math.round(scrollX), scrollY: Math.round(scrollY) })');+ return success({ direction, ...(position.ok ? (position.data as object) : {}) });+}++interface ShotPlan {+ mode: 'fullPage' | 'viewport' | 'element';+ dpr: number;+ viewport: { w: number; h: number };+ region: { x: number; y: number; w: number; h: number };+ format: 'png' | 'jpeg';+ quality?: number;+ maxLongSide: number;+}++/** A screenshot's clip in CSS px, its scale against device pixels, and the image size that comes out (spike Q9). */+export function shotClip(plan: ShotPlan): { clip: { x: number; y: number; width: number; height: number; scale: number }; width: number; height: number; truncated: boolean } {+ const height = Math.min(plan.region.h, plan.viewport.h * MAX_SHOT_SCREENS);+ const fit = Math.min(1, plan.maxLongSide / Math.max(plan.region.w, height));+ return {+ clip: { x: plan.region.x, y: plan.region.y, width: plan.region.w, height, scale: fit / (plan.dpr || 1) },+ width: Math.max(1, Math.round(plan.region.w * fit)),+ height: Math.max(1, Math.round(height * fit)),+ truncated: height < plan.region.h,+ };+}++async function screenshotOn(here: Here, input: unknown): Promise<ActionResult> {+ const planned = await inPage(here, 'page.screenshot', input, await topFrame(here));+ if (!planned.ok) return planned;+ const plan = planned.data as ShotPlan;+ const { clip, width, height, truncated } = shotClip(plan);+ const shot = await here.cdp(+ 'Page.captureScreenshot',+ { format: plan.format, ...(plan.format === 'jpeg' ? { quality: plan.quality ?? 80 } : {}), clip, captureBeyondViewport: plan.mode !== 'viewport', fromSurface: true },+ 30_000,+ );+ if (!shot.ok) return shot;+ return success({ format: plan.format, width, height, dataUrl: `data:image/${plan.format};base64,${String(shot.data.data)}`, ...(truncated ? { truncated } : {}) });+}++async function switchFrameOn(here: Here, input: unknown): Promise<ActionResult> {+ const parsed = switchFrame.input.safeParse(input ?? {});+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));+ const { frame, to } = parsed.data;+ const { frameId, path } = await focusedFrame(here);+ if (!frame) {+ const frames = to === 'parent' ? path.slice(0, -1) : [];+ framePaths.set(here.targetId, { url: here.url, frames });+ return success({ frame: frames.length ? { depth: frames.length } : 'top' });+ }+ const element = await evaluateIn(here, frameId, `${PHONE_API}.frame(${JSON.stringify(frame)})`, { byValue: false });+ if (!element.ok) return element;+ const described = await here.cdp('DOM.describeNode', { objectId: (element.data as { objectId?: string }).objectId });+ const childFrame = described.ok ? (described.data.node as { frameId?: string } | undefined)?.frameId : undefined;+ if (!childFrame) return failure('UNSUPPORTED', 'That frame cannot be entered on the phone: Chrome keeps it in another process.');+ const frames = [...path, childFrame];+ framePaths.set(here.targetId, { url: here.url, frames });+ return success({ frame: { depth: frames.length, frameId: childFrame } });+}++async function thenLoaded(here: Here, action: string, input: unknown): Promise<ActionResult> {+ const result = await inPage(here, action, input);+ if (!result.ok) return result;+ await pause(SETTLE_MS);+ const landing = await waitForLoad(here);+ return success({ ...(result.data as object), finalUrl: landing.url, loaded: landing.loaded });+}++type PhoneTool = (here: Here, input: Record<string, unknown>, action: string) => Promise<ActionResult>;++const TOOLS: Record<string, PhoneTool> = {+ 'page.clickElement': (here, input) => tapOn(here, input, true),+ 'page.trustedClick': (here, input) => tapOn(here, input, false),+ 'page.dragElement': dragOn,+ 'page.typeText': typeOn,+ 'page.pressKey': pressOn,+ 'page.scrollTo': scrollOn,+ 'page.screenshot': screenshotOn,+ 'page.switchFrame': switchFrameOn,+ 'page.searchSite': (here, input, action) => thenLoaded(here, action, input),+ 'page.submitForm': (here, input, action) => thenLoaded(here, action, input),+};++/** Every page-side tool on the phone: its own code in the page where it can be, real input where the page cannot fake it. */+export async function pageSideOnPhone(action: string, input: unknown, phone: PhoneSession): Promise<ActionResult> {+ const here = await hereOn(phone);+ if (!here) return failure('PHONE_GONE', GONE);+ const tool = TOOLS[action];+ return tool ? tool(here, (input ?? {}) as Record<string, unknown>, action) : inPage(here, action, input);+}diff --git a/src/lib/bridge/phone-invoke.ts b/src/lib/bridge/phone-invoke.tsindex 27cb05a..af7a39e 100644--- a/src/lib/bridge/phone-invoke.ts+++ b/src/lib/bridge/phone-invoke.ts@@ -8,7 +8,8 @@ import { switchTab } from '@/lib/actions/page/switch-tab';import { failure, success, type ActionResult } from '@/lib/actions/protocol';import { EXPIRED_MESSAGE, REFUSED_MESSAGE } from '@/lib/secrets';import { notOnPhone, phoneOffers } from '@/lib/phone/features';-import { isLive, readPhone, targetForNumber, updatePhone, numbered, type PhoneSession } from './phone';+import { currentTarget, isLive, readPhone, targetForNumber, updatePhone, numbered, type PhoneSession } from './phone';+import { hereOn, pageSideOnPhone, waitForLoad } from './phone-backend';import { attachedSession, bringToFront, followTarget } from './phone-mirror';import { releaseForAction, sealForPage } from './secret-vault';import { refusalFor } from './site-guard';@@ -16,15 +17,12 @@ import { sendCdp } from './socket';import { sessionForRun, type TabSession } from './tab-sessions';const GONE = 'The phone disconnected. Reconnect it and switch Android on again.';-const LOAD_TIMEOUT_MS = 15_000;-const LOAD_POLL_MS = 150;/** Pages a tool lands on, checked against the blocked list once it has run. */const LANDS = new Set([navigate.name, openTab.name, 'page.searchSite', 'page.submitForm', 'page.clickElement', 'page.trustedClick']);type PhoneBackend = (action: string, input: unknown, phone: PhoneSession) => Promise<ActionResult>;-const pageSide: PhoneBackend = async (action) => failure('NOT_BUILT', `${action} is not built for the phone yet.`);/*** The phone session a call belongs to: its run's conversation lives on the phone tab, or, with no@@ -40,7 +38,7 @@ export async function phoneRoute(tabId: number | undefined, runId: string | undereturn isLive(phone) ? phone : 'gone';}-export const currentTarget = (phone: PhoneSession) => phone.targets.find((target) => target.targetId === phone.activeTargetId) ?? phone.targets[0];+export { currentTarget };export async function invokeOnPhone(action: string, input: unknown, route: PhoneSession | 'gone'): Promise<ActionResult> {if (route === 'gone') return failure('PHONE_GONE', GONE);@@ -54,7 +52,7 @@ export async function invokeOnPhone(action: string, input: unknown, route: Phoneif (release.refused.length) return failure('SECRET_NOT_RELEASABLE', REFUSED_MESSAGE);if (release.unresolved.length) return failure('SECRET_EXPIRED', EXPIRED_MESSAGE);- const result = await (TAB_TOOLS[action] ?? pageSide)(action, release.input, route);+ const result = await (TAB_TOOLS[action] ?? pageSideOnPhone)(action, release.input, route);if (result.ok && LANDS.has(action)) {const landed = await refusalFor(currentTarget((await readPhone()) ?? route)?.url, textOf((result.data as { finalUrl?: unknown })?.finalUrl));if (landed) return landed;@@ -86,20 +84,9 @@ export async function inCurrentTab(phone: PhoneSession, method: string, params?:return sessionId ? sendCdp(phone.serial, method, params, sessionId) : failure('PHONE_GONE', GONE);}-async function loaded(phone: PhoneSession, sinceUrl?: string): Promise<{ url: string; title: string; loaded: boolean }> {- const deadline = Date.now() + LOAD_TIMEOUT_MS;- let seen = { url: sinceUrl ?? '', title: '', readyState: '' };- while (Date.now() < deadline) {- await new Promise((resolve) => setTimeout(resolve, LOAD_POLL_MS));- const state = await inCurrentTab(phone, 'Runtime.evaluate', {- expression: 'JSON.stringify({ url: location.href, title: document.title, readyState: document.readyState })',- returnByValue: true,- });- if (!state.ok) continue;- seen = JSON.parse(String((state.data.result as { value?: unknown }).value ?? '{}'));- if (seen.readyState === 'complete' && seen.url !== 'about:blank') return { url: seen.url, title: seen.title, loaded: true };- }- return { url: seen.url, title: seen.title, loaded: false };+async function loaded(phone: PhoneSession): Promise<{ url: string; title: string; loaded: boolean }> {+ const here = await hereOn(phone);+ return here ? waitForLoad(here) : { url: currentTarget(phone)?.url ?? '', title: '', loaded: false };}async function navigateOnPhone(_action: string, input: unknown, phone: PhoneSession): Promise<ActionResult> {diff --git a/src/lib/bridge/phone.ts b/src/lib/bridge/phone.tsindex 5f4ae6b..52c924c 100644--- a/src/lib/bridge/phone.ts+++ b/src/lib/bridge/phone.ts@@ -41,6 +41,9 @@ export function numbered(session: PhoneSession, targets: PhoneTarget[] = sessionreturn { ...session, targets, tabNumbers };}+export const currentTarget = (phone: PhoneSession): PhoneTarget | undefined =>+ phone.targets.find((target) => target.targetId === phone.activeTargetId) ?? phone.targets[0];+export const targetForNumber = (session: PhoneSession, number: number): string | undefined =>Object.entries(session.tabNumbers ?? {}).find(([, value]) => value === number)?.[0];diff --git a/src/lib/bridge/socket.ts b/src/lib/bridge/socket.tsindex 18816b3..e8ad756 100644--- a/src/lib/bridge/socket.ts+++ b/src/lib/bridge/socket.ts@@ -413,8 +413,9 @@ export function sendCdp(method: string,params?: Record<string, unknown>,sessionId?: string,+ timeoutMs?: number,): Promise<ActionResult<Record<string, unknown>>> {- return phoneOp({ t: 'cdp', id: crypto.randomUUID(), serial, method, params, sessionId }, PHONE_COMMAND_TIMEOUT_MS);+ return phoneOp({ t: 'cdp', id: crypto.randomUUID(), serial, method, params, sessionId, timeoutMs }, (timeoutMs ?? 0) + PHONE_COMMAND_TIMEOUT_MS);}export function closePhone(serial: string): void {diff --git a/src/lib/phone/features.ts b/src/lib/phone/features.tsindex 91a84e9..b14ee74 100644--- a/src/lib/phone/features.ts+++ b/src/lib/phone/features.ts@@ -34,6 +34,9 @@ export const PHONE_TOOLS: ReadonlySet<string> = new Set([export const PHONE_RESERVED: ReadonlySet<string> = new Set();+/** Tools that touch no page and keep their state in the browser, so a phone run uses them exactly as a desktop one does. */+export const HOST_SIDE: ReadonlySet<string> = new Set(['page.startTimer', 'page.timerStatus', 'page.stopTimer']);+export const phoneOffers = (action: string): boolean => PHONE_TOOLS.has(action) || PHONE_RESERVED.has(action);export const notOnPhone = (action: string): string => `${action} isn’t available on the phone. It works in desktop tabs.`;diff --git a/src/lib/phone/page-api.test.ts b/src/lib/phone/page-api.test.tsnew file mode 100644index 0000000..f5316ae--- /dev/null+++ b/src/lib/phone/page-api.test.ts@@ -0,0 +1,24 @@+import { fileURLToPath } from 'node:url';+import { build, type Rollup } from 'vite';+import { describe, expect, test } from 'vitest';++const src = fileURLToPath(new URL('../..', import.meta.url));++/** The phone's page bundle as the extension ships it, minus WXT's wrapper: everything the phone page's isolated world will run. */+async function bundled(): Promise<string> {+ const output = (await build({+ configFile: false,+ logLevel: 'silent',+ resolve: { alias: [{ find: /^@\//, replacement: `${src}/` }] },+ build: { write: false, minify: false, lib: { entry: fileURLToPath(new URL('./page-api.ts', import.meta.url)), formats: ['iife'], name: 'phonePage' } },+ })) as Rollup.RollupOutput[];+ return output[0].output.map((chunk) => ('code' in chunk ? chunk.code : '')).join('\n');+}++describe('the page bundle a phone page runs', () => {+ test('reaches for no extension API, since there is none in a phone page', async () => {+ const code = await bundled();+ expect(code).toContain('__browsenticPhone');+ expect(code.match(/\b(?:chrome|browser)\.(?:runtime|tabs|storage|scripting|debugger)\b/g)).toBeNull();+ }, 60_000);+});diff --git a/src/lib/phone/page-api.ts b/src/lib/phone/page-api.tsnew file mode 100644index 0000000..40ea0c6--- /dev/null+++ b/src/lib/phone/page-api.ts@@ -0,0 +1,26 @@+import { dispatch } from '@/lib/actions/dispatch';+import { resolveTarget, targetSchema } from '@/lib/actions/page/dom';+import { isFrameElement } from '@/lib/actions/page/switch-frame';++export const PHONE_API = '__browsenticPhone';++/**+ * What the phone's page bundle puts in its isolated world: the actions' own `dispatch`, the+ * visual viewport a touch is measured from, and the frame element a frame switch enters.+ */+export function installPhoneApi(): void {+ (globalThis as Record<string, unknown>)[PHONE_API] = {+ dispatch,+ viewport: () => ({+ left: visualViewport?.offsetLeft ?? 0,+ top: visualViewport?.offsetTop ?? 0,+ width: visualViewport?.width ?? innerWidth,+ height: visualViewport?.height ?? innerHeight,+ }),+ frame: (target: unknown) => {+ const element = resolveTarget(targetSchema.parse(target));+ if (!isFrameElement(element)) throw new Error(`<${element.tagName.toLowerCase()}> is not an <iframe>; pick one of the frames page.getPageInfo lists`);+ return element;+ },+ };+}diff --git a/src/lib/phone/touch.test.ts b/src/lib/phone/touch.test.tsnew file mode 100644index 0000000..acfb95f--- /dev/null+++ b/src/lib/phone/touch.test.ts@@ -0,0 +1,66 @@+import { describe, expect, test } from 'vitest';+import { drag, keyPress, onScreen, tap, typing, wheel } from './touch';++const VIEWPORT = { offsetX: 0, offsetY: 0, width: 411, height: 675 };++describe('where a touch lands', () => {+ test('a page point less the visual viewport’s offset, unscaled by the zoom', () => {+ expect(onScreen({ x: 250, y: 400 }, { ...VIEWPORT, offsetX: 50, offsetY: 100, width: 205, height: 337 })).toEqual({ x: 200, y: 300 });+ });++ test('a point off the visible screen is no touch at all', () => {+ expect(onScreen({ x: 100, y: 700 }, VIEWPORT)).toBeNull();+ expect(onScreen({ x: -1, y: 10 }, VIEWPORT)).toBeNull();+ });+});++describe('gestures', () => {+ test('a tap is a touch held 50 ms, then lifted', () => {+ expect(tap({ x: 10, y: 20 })).toEqual([+ { method: 'Input.dispatchTouchEvent', params: { type: 'touchStart', touchPoints: [{ x: 10, y: 20 }] }, waitMs: 50 },+ { method: 'Input.dispatchTouchEvent', params: { type: 'touchEnd', touchPoints: [] }, waitMs: undefined },+ ]);+ });++ test('a drag moves in steps and holds 120 ms at the drop before lifting, so nothing flings on', () => {+ const steps = drag({ x: 0, y: 0 }, { x: 0, y: 300 }, 3);+ expect(steps.map(({ params }) => [params.type, (params.touchPoints as { y: number }[])[0]?.y])).toEqual([+ ['touchStart', 0],+ ['touchMove', 100],+ ['touchMove', 200],+ ['touchMove', 300],+ ['touchEnd', undefined],+ ]);+ expect(steps.at(-2)?.waitMs).toBe(120);+ });++ test('scrolling by an amount is wheel steps of 120 that add up exactly', () => {+ const steps = wheel({ x: 200, y: 300 }, 600);+ expect(steps).toHaveLength(5);+ expect(steps.every(({ params }) => params.type === 'mouseWheel' && params.deltaY === 120)).toBe(true);+ expect(wheel({ x: 0, y: 0 }, -250).reduce((sum, { params }) => sum + Number(params.deltaY), 0)).toBe(-250);+ });+});++describe('keys and text', () => {+ test('Enter submits as keyDown with its text', () => {+ expect(keyPress('Enter')[0].params).toMatchObject({ type: 'keyDown', key: 'Enter', windowsVirtualKeyCode: 13, text: '\r' });+ });++ test('Backspace carries its virtual key code, without which nothing is deleted', () => {+ expect(keyPress('Backspace')[0].params).toMatchObject({ type: 'rawKeyDown', code: 'Backspace', windowsVirtualKeyCode: 8 });+ expect(keyPress('Backspace')[0].params.text).toBeUndefined();+ });++ test('a printable key types itself, and a shortcut types nothing', () => {+ expect(keyPress('a')[0].params).toMatchObject({ type: 'keyDown', text: 'a', code: 'KeyA', modifiers: 0 });+ expect(keyPress('a', ['ctrl'])[0].params).toMatchObject({ type: 'rawKeyDown', modifiers: 2 });+ expect(keyPress('A', ['shift'])[0].params).toMatchObject({ type: 'keyDown', text: 'A', modifiers: 8 });+ });++ test('typing inserts text in chunks, and a newline is an Enter press', () => {+ const steps = typing('héllo 👋\nsecond line');+ expect(steps.map(({ method, params }) => (method === 'Input.insertText' ? params.text : params.type))).toEqual(['héllo 👋', 'keyDown', 'keyUp', 'second line']);+ expect(typing('x'.repeat(150)).map(({ params }) => String(params.text).length)).toEqual([64, 64, 22]);+ });+});diff --git a/src/lib/phone/touch.ts b/src/lib/phone/touch.tsnew file mode 100644index 0000000..1155891--- /dev/null+++ b/src/lib/phone/touch.ts@@ -0,0 +1,90 @@+import { keyboardInit, type Modifier } from '@/lib/actions/page/keyboard';++export interface Point {+ x: number;+ y: number;+}++export interface Viewport {+ /** The visual viewport's offset into the layout viewport, as `Page.getLayoutMetrics` gives it. */+ offsetX: number;+ offsetY: number;+ width: number;+ height: number;+}++/** One CDP input event, and how long to wait before the next. */+export interface InputStep {+ method: 'Input.dispatchTouchEvent' | 'Input.dispatchMouseEvent' | 'Input.dispatchKeyEvent' | 'Input.insertText';+ params: Record<string, unknown>;+ waitMs?: number;+}++const TAP_HOLD_MS = 50;+const DRAG_STEP_MS = 16;+/** A drag that ends without a pause flings on: 500 px dragged scrolled 587 (spike Q6). */+const DRAG_HOLD_MS = 120;+const WHEEL_STEP = 120;+const TEXT_CHUNK = 64;++/**+ * Where a page point lands for a touch: CSS px from the visual viewport's corner, never scaled by+ * the zoom (spike Q5). Null when it is off the visible part of the screen, where Chrome would still+ * deliver it without complaint.+ */+export function onScreen(point: Point, viewport: Viewport): Point | null {+ const x = point.x - viewport.offsetX;+ const y = point.y - viewport.offsetY;+ return x >= 0 && y >= 0 && x <= viewport.width && y <= viewport.height ? { x, y } : null;+}++const touch = (type: string, at?: Point, waitMs?: number): InputStep => ({+ method: 'Input.dispatchTouchEvent',+ params: { type, touchPoints: at ? [{ x: at.x, y: at.y }] : [] },+ waitMs,+});++export const tap = (at: Point): InputStep[] => [touch('touchStart', at, TAP_HOLD_MS), touch('touchEnd')];++export function drag(from: Point, to: Point, steps: number): InputStep[] {+ const moves = Array.from({ length: Math.max(1, steps) }, (_, index) => {+ const t = (index + 1) / Math.max(1, steps);+ return touch('touchMove', { x: from.x + (to.x - from.x) * t, y: from.y + (to.y - from.y) * t }, DRAG_STEP_MS);+ });+ const hold = moves[moves.length - 1];+ return [touch('touchStart', from, DRAG_STEP_MS), ...moves.slice(0, -1), { ...hold, waitMs: DRAG_HOLD_MS }, touch('touchEnd')];+}++/** Scrolling by an amount is mouse wheels: exact, and later taps keep their pointer events, which a synthesized scroll gesture takes away once the page is zoomed (spike Q6). */+export function wheel(at: Point, deltaY: number): InputStep[] {+ const count = Math.max(1, Math.ceil(Math.abs(deltaY) / WHEEL_STEP));+ const step = deltaY / count;+ return Array.from({ length: count }, () => ({+ method: 'Input.dispatchMouseEvent' as const,+ params: { type: 'mouseWheel', x: at.x, y: at.y, deltaX: 0, deltaY: step },+ waitMs: DRAG_STEP_MS,+ }));+}++const MODIFIER_BITS: Record<Modifier, number> = { alt: 1, ctrl: 2, meta: 4, shift: 8 };++/** Enter submits only as `keyDown` with its text, Backspace edits only with its virtual key code, printable keys are `keyDown` with text (spike Q7). */+export function keyPress(key: string, modifiers: Modifier[] = []): InputStep[] {+ const { code, keyCode } = keyboardInit(key, modifiers);+ const mask = modifiers.reduce((bits, modifier) => bits | MODIFIER_BITS[modifier], 0);+ const plain = mask === 0 || mask === MODIFIER_BITS.shift;+ const text = key === 'Enter' ? '\r' : key.length === 1 && plain ? key : undefined;+ const base = { key, code, windowsVirtualKeyCode: keyCode, nativeVirtualKeyCode: keyCode, modifiers: mask };+ return [+ { method: 'Input.dispatchKeyEvent', params: { type: text ? 'keyDown' : 'rawKeyDown', ...base, ...(text ? { text, unmodifiedText: text } : {}) } },+ { method: 'Input.dispatchKeyEvent', params: { type: 'keyUp', ...base } },+ ];+}++/** Text goes in as `Input.insertText`, which types accents and emoji; a newline is an Enter press. */+export function typing(text: string): InputStep[] {+ return text.split('\n').flatMap((line, index) => [+ ...(index ? keyPress('Enter') : []),+ ...(line.match(new RegExp(`[\\s\\S]{1,${TEXT_CHUNK}}`, 'gu')) ?? []).map((chunk): InputStep => ({ method: 'Input.insertText', params: { text: chunk } })),+ ]);+}