@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/mcp/browser/headless-tab.ts

@@ -0,0 +1,575 @@
+import type { CDPSession, Dialog, Frame, Page } from 'playwright-core'
+
+import { formatSnapshot, RefBook, type Snapshot } from './ax-snapshot'
+import { credentialsIn, redactWith, STUDIO_SESSION } from './credentials'
+import { conditionHolds, FRAMES_AGAIN_MS, PageFrames, type Cdp, type PageFrame } from './frames'
+import type { KeyPress } from './keys'
+import { CARET_TO_END, evaluateOnElement, evaluateWrapper, FOCUS, PAGE_TEXT, SELECT_CONTENTS, SELECT_OPTIONS, selectorVisible, textPresent, VISIBLE } from './page-scripts'
+import type { WaitCondition } from './wait'
+
+/**
+ * One page of the headless browser: a Playwright page driven through its
+ * DevTools Protocol session the way Forge drives a tab of its Browser, so a
+ * snapshot, its refs and every action behave the same in both. Refs are DOM
+ * nodes (`backendNodeId`): a ref keeps naming its element until the page
+ * goes to another document. Frames (an App embedded in Studio) are read into
+ * the snapshot and acted in through `PageFrames`; a frame Chrome renders in a
+ * process of its own is reached through a DevTools session of its own.
+ */
+
+const CONSOLE_KEEP = 500
+const NETWORK_KEEP = 500
+const CDP_TIMEOUT_MS = 20_000
+
+export type DeviceWidth = 'desktop' | 'tablet' | 'phone'
+export const DEVICE_SIZES: Record<DeviceWidth, { label: string; width: number; height: number }> = {
+  desktop: { label: 'Desktop · 1440', width: 1440, height: 900 },
+  tablet: { label: 'Tablet · 768', width: 768, height: 1024 },
+  phone: { label: 'Phone · 375', width: 375, height: 812 },
+}
+
+export interface ConsoleEntry {
+  level: 'error' | 'warning' | 'info' | 'log' | 'debug'
+  text: string
+  source: string | null
+  at: number
+}
+
+export interface NetworkEntry {
+  id: string
+  method: string
+  url: string
+  status: number | null
+  type: string
+  ms: number | null
+  failed: string | null
+  at: number
+}
+
+/** A request that failed: refused, aborted, or answered 400 or above. */
+export const requestFailed = (n: Pick<NetworkEntry, 'failed' | 'status'>): boolean => !!n.failed || (n.status ?? 0) >= 400
+
+/**
+ * `browser_network`'s answer: the requests, failed ones first (only them with
+ * `onlyFailed`), and how many were captured when none is shown, so "none
+ * failed" never reads as "nothing was captured".
+ */
+export function networkText(entries: readonly NetworkEntry[], onlyFailed: boolean, limit = 200): string {
+  const failed = entries.filter(requestFailed)
+  const shown = (onlyFailed ? failed : [...failed, ...entries.filter((n) => !requestFailed(n))]).slice(0, limit)
+  if (!entries.length) return 'No requests captured since the tab opened.'
+  if (!shown.length) return `${entries.length} request${entries.length === 1 ? '' : 's'} captured since the tab opened; none failed.`
+  const lines = shown.map((n) => `${n.method} ${n.url.slice(0, 200)} → ${n.failed ?? n.status ?? 'pending'}${n.ms !== null ? ` (${n.ms} ms)` : ''}`)
+  // With onlyFailed, the rest are said as a count: what was captured besides the failures.
+  const rest = onlyFailed ? entries.length - failed.length : 0
+  return [...lines, ...(rest ? [`${rest} more request${rest === 1 ? '' : 's'} captured, none failed.`] : [])].join('\n')
+}
+
+export interface PageDialog {
+  type: 'alert' | 'confirm' | 'prompt' | 'beforeunload'
+  message: string
+  defaultPrompt: string
+  at: number
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+/** A loopback address, or a page with no address: what belongs to the project on this machine. */
+export function isProjectAddress(url: string): boolean {
+  try {
+    const { hostname, protocol } = new URL(url)
+    if (protocol === 'about:' || protocol === 'data:') return true
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname.endsWith('.localhost')
+  } catch {
+    return false
+  }
+}
+
+/** The site an address belongs to, for an answer: `github.com`. */
+export function siteOf(url: string): string {
+  try {
+    return new URL(url).host
+  } catch {
+    return url
+  }
+}
+
+let nextId = 0
+
+export class HeadlessTab {
+  readonly id = `h${++nextId}`
+  readonly createdAt = Date.now()
+  device: DeviceWidth = 'desktop'
+  viewport: { width: number; height: number | null } | null = null
+  /** When the agent last acted in it. */
+  agentAt = Date.now()
+  snapshot: Snapshot | null = null
+  snapshotAt = 0
+  navigatedAt = 0
+  readonly refs = new RefBook()
+  dialog: PageDialog | null = null
+  console: ConsoleEntry[] = []
+  network = new Map<string, NetworkEntry>()
+  private pendingDialog: Dialog | null = null
+  private dialogWaiters = new Set<() => void>()
+  /** Each secret this tab has seen, with what it is shown as instead. */
+  private secrets = new Map<string, string>()
+  private inflight = new Set<string>()
+  private requestIds = new WeakMap<object, string>()
+  private requestCounter = 0
+  private closed = false
+  readonly frames: PageFrames
+  /** Sessions of the frames Chrome renders in a process of their own, by frame id. */
+  private frameSessions = new Map<string, { session: CDPSession; cdp: Cdp }>()
+  private frameIds = new WeakMap<Frame, string | null>()
+
+  private constructor(
+    readonly page: Page,
+    private readonly session: CDPSession,
+    /** The project folder the tab was opened for, where its screenshots go. */
+    readonly root: string,
+  ) {
+    this.frames = new PageFrames({ root: (method, params) => this.cdp(method, params), outOfProcess: (frameId) => this.outOfProcess(frameId) }, 'frontera')
+  }
+
+  /** One DevTools command on a session, bounded. */
+  private bounded<T>(session: CDPSession, method: string, params: Record<string, unknown>): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    return (Promise.race([
+      session.send(method as never, params as never),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`the page did not answer ${method}`)), CDP_TIMEOUT_MS)
+      }),
+    ]) as Promise<T>).finally(() => clearTimeout(timer))
+  }
+
+  /**
+   * A frame Chrome renders in a process of its own has a session of its own;
+   * Playwright opens one for such a frame, and refuses for a frame that
+   * renders in its parent's process.
+   */
+  private async outOfProcess(frameId: string): Promise<Cdp | null> {
+    const known = this.frameSessions.get(frameId)
+    if (known) return known.cdp
+    for (const frame of this.page.frames()) {
+      if (frame === this.page.mainFrame() || this.frameIds.has(frame)) continue
+      try {
+        const session = await this.page.context().newCDPSession(frame)
+        const tree = await this.bounded<{ frameTree: { frame: { id: string } } }>(session, 'Page.getFrameTree', {})
+        const id = tree.frameTree.frame.id
+        this.frameIds.set(frame, id)
+        const cdp: Cdp = (method, params) => (this.alive ? this.bounded(session, method, params ?? {}) : Promise.reject(new Error('the page is closed')))
+        this.frameSessions.set(id, { session, cdp })
+        await Promise.all([cdp('DOM.enable'), cdp('Page.enable'), cdp('Runtime.enable')]).catch(() => {})
+      } catch {
+        this.frameIds.set(frame, null)
+      }
+    }
+    return this.frameSessions.get(frameId)?.cdp ?? null
+  }
+
+  /** A frame that navigated may have moved to another process: look its session up again. */
+  private forgetFrame(frame: Frame): void {
+    const id = this.frameIds.get(frame)
+    this.frameIds.delete(frame)
+    if (!id) return
+    const held = this.frameSessions.get(id)
+    this.frameSessions.delete(id)
+    this.frames.frameNavigated(id)
+    void held?.session.detach().catch(() => {})
+  }
+
+  static async open(page: Page, root: string): Promise<HeadlessTab> {
+    const session = await page.context().newCDPSession(page)
+    const tab = new HeadlessTab(page, session, root)
+    tab.attach()
+    await Promise.all([session.send('DOM.enable'), session.send('Page.enable'), session.send('Runtime.enable')]).catch(() => {})
+    return tab
+  }
+
+  get alive(): boolean {
+    return !this.closed && !this.page.isClosed()
+  }
+
+  /** One DevTools command, bounded: a page that is gone must not hold the agent. */
+  async cdp<T = Record<string, unknown>>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    if (!this.alive) throw new Error('the page is closed')
+    return this.bounded<T>(this.session, method, params)
+  }
+
+  private attach(): void {
+    const { page } = this
+    // Another document: its nodes, and so its refs, are new. Same-document navigations keep them.
+    this.session.on('Page.frameNavigated', (p: { frame: { id: string; parentId?: string } }) => {
+      if (p.frame.parentId) {
+        this.frames.frameNavigated(p.frame.id)
+        return
+      }
+      this.navigatedAt = Date.now()
+      this.refs.reset()
+      this.frames.reset()
+    })
+    page.on('framenavigated', (f) => {
+      // A frame's address can carry a credential (an App's launch token).
+      this.noteSecretsIn(f.url())
+      if (f !== page.mainFrame()) this.forgetFrame(f)
+    })
+    page.on('framedetached', (f) => this.forgetFrame(f))
+    page.on('console', (m) => {
+      const type = m.type()
+      const level: ConsoleEntry['level'] = type === 'error' || type === 'assert' ? 'error' : type === 'warning' ? 'warning' : type === 'info' ? 'info' : type === 'debug' ? 'debug' : 'log'
+      const loc = m.location()
+      this.pushConsole({ level, text: m.text().slice(0, 2_000), source: loc?.url ? `${loc.url.split('/').pop()}:${(loc.lineNumber ?? 0) + 1}` : null, at: Date.now() })
+    })
+    page.on('pageerror', (e) => this.pushConsole({ level: 'error', text: `Uncaught ${String(e?.stack ?? e?.message ?? e).slice(0, 2_000)}`, source: null, at: Date.now() }))
+    page.on('request', (r) => {
+      if (r.url().startsWith('data:')) return
+      // Before the request is listed: its address can carry a credential (an App frame's launch token).
+      this.noteSecretsIn(r.url())
+      const id = `r${++this.requestCounter}`
+      this.requestIds.set(r, id)
+      this.inflight.add(id)
+      this.putNetwork({ id, method: r.method(), url: r.url(), status: null, type: r.resourceType(), ms: null, failed: null, at: Date.now() })
+    })
+    page.on('response', (res) => {
+      const id = this.requestIds.get(res.request())
+      const entry = id ? this.network.get(id) : undefined
+      if (entry) this.putNetwork({ ...entry, status: res.status() })
+    })
+    const finish = (r: import('playwright-core').Request, failed: string | null) => {
+      const id = this.requestIds.get(r)
+      if (!id) return
+      this.inflight.delete(id)
+      const entry = this.network.get(id)
+      if (entry) this.putNetwork({ ...entry, ms: Date.now() - entry.at, failed })
+    }
+    page.on('requestfinished', (r) => finish(r, null))
+    page.on('requestfailed', (r) => finish(r, r.failure()?.errorText ?? 'failed'))
+    // With a listener, Playwright leaves the dialog open until it is answered, as a person would see it.
+    page.on('dialog', (d) => {
+      const type = d.type()
+      this.pendingDialog = d
+      this.dialog = {
+        type: type === 'confirm' || type === 'prompt' || type === 'beforeunload' ? type : 'alert',
+        message: this.redact(d.message()).slice(0, 2_000),
+        defaultPrompt: d.defaultValue(),
+        at: Date.now(),
+      }
+      for (const wake of this.dialogWaiters) wake()
+    })
+    page.on('close', () => {
+      this.closed = true
+    })
+  }
+
+  /** Never show a secret this tab was given or saw: `text` with each one blanked out. */
+  redact(text: string): string {
+    return redactWith(text, this.secrets)
+  }
+
+  /** A credential on a local address (a signed Studio link, an App's launch token) is a secret from here on. */
+  noteSecretsIn(url: string): void {
+    for (const c of credentialsIn(url)) this.addSecret(c.secret, c.label)
+  }
+
+  addSecret(secret: string | null | undefined, label = STUDIO_SESSION): void {
+    if (secret && secret.length >= 8 && !this.secrets.has(secret)) this.secrets.set(secret, label)
+  }
+
+  private pushConsole(entry: ConsoleEntry): void {
+    if (this.secrets.size) entry = { ...entry, text: this.redact(entry.text), source: entry.source ? this.redact(entry.source) : null }
+    this.console.push(entry)
+    if (this.console.length > CONSOLE_KEEP) this.console.splice(0, this.console.length - CONSOLE_KEEP)
+  }
+
+  private putNetwork(entry: NetworkEntry): void {
+    if (this.secrets.size) entry = { ...entry, url: this.redact(entry.url) }
+    this.network.set(entry.id, entry)
+    if (this.network.size > NETWORK_KEEP) this.network.delete(this.network.keys().next().value!)
+  }
+
+  get url(): string {
+    return this.alive ? this.redact(this.page.url()) : ''
+  }
+
+  async title(): Promise<string> {
+    return this.alive ? this.redact(await this.page.title().catch(() => '')) : ''
+  }
+
+  /** Load an address and wait for its document, bounded; why it failed, or null. */
+  async load(url: string, timeoutMs = 30_000): Promise<string | null> {
+    this.noteSecretsIn(url)
+    try {
+      await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: timeoutMs })
+      return null
+    } catch (err) {
+      const message = (err as Error).message
+      // A redirect, or a page that aborted its own load, still shows something.
+      if (/ERR_ABORTED/.test(message)) return null
+      // A dialog during load holds it; the page is where it is.
+      if (this.dialog) return null
+      return this.redact(message.split('\n')[0] ?? message).slice(0, 300)
+    }
+  }
+
+  /** Back, forward or reload, waiting for the page it went to; why it failed, or null. */
+  async go(action: 'back' | 'forward' | 'reload', timeoutMs = 30_000): Promise<string | null> {
+    try {
+      if (action === 'reload') {
+        await this.page.reload({ waitUntil: 'domcontentloaded', timeout: timeoutMs })
+        return null
+      }
+      const h = await this.cdp<{ currentIndex: number; entries: unknown[] }>('Page.getNavigationHistory').catch(() => null)
+      if (h && action === 'back' && h.currentIndex <= 0) return 'There is no page to go back to.'
+      if (h && action === 'forward' && h.currentIndex >= h.entries.length - 1) return 'There is no page to go forward to.'
+      // Null for a step inside the same document, which still moved the page.
+      if (action === 'back') await this.page.goBack({ waitUntil: 'domcontentloaded', timeout: timeoutMs })
+      else await this.page.goForward({ waitUntil: 'domcontentloaded', timeout: timeoutMs })
+      return null
+    } catch (err) {
+      const message = (err as Error).message
+      return /ERR_ABORTED/.test(message) ? null : this.redact(message.split('\n')[0] ?? message).slice(0, 300)
+    }
+  }
+
+  /**
+   * Wait until no request runs for a moment, bounded: a dev server's
+   * websocket never closes, so this never fails. True when the page went
+   * quiet, false when the time ran out first.
+   */
+  async settle(maxMs = 8_000, quietMs = 500): Promise<boolean> {
+    const deadline = Date.now() + maxMs
+    let quietSince = this.inflight.size === 0 ? Date.now() : 0
+    while (Date.now() < deadline && this.alive) {
+      await sleep(100)
+      if (this.dialog) return false
+      if (this.inflight.size) quietSince = 0
+      else if (!quietSince) quietSince = Date.now()
+      else if (Date.now() - quietSince >= quietMs) return true
+    }
+    return false
+  }
+
+  /** Evaluate the browser's own expression in the main document's isolated world. */
+  evaluate<T>(expression: string): Promise<T | null> {
+    return this.frames.evaluate<T>(this.frames.main, expression)
+  }
+
+  /** Call the browser's function on an element (its handle), in its frame's isolated world. */
+  callOn<T>(handle: number, fn: string, args: unknown[] = []): Promise<T | null> {
+    return this.frames.callOn<T>(handle, fn, args)
+  }
+
+  async takeSnapshot(): Promise<Snapshot> {
+    const { nodes, frames } = await this.frames.snapshotTree()
+    const snap = formatSnapshot(nodes, { url: this.url, title: await this.title(), refFor: this.refs.refFor, frames })
+    this.snapshot = this.secrets.size ? { ...snap, text: this.redact(snap.text) } : snap
+    this.snapshotAt = Date.now()
+    return this.snapshot
+  }
+
+  nodeForRef(ref: string): number | undefined {
+    return this.refs.node(ref)
+  }
+
+  /** The address of the frame an element is in, null for one on the page itself. */
+  frameAddressOf(handle: number): string | null {
+    return this.frames.addressOf(handle)
+  }
+
+  async isShown(backendNodeId: number): Promise<boolean> {
+    try {
+      return (await this.callOn<boolean>(backendNodeId, VISIBLE)) === true
+    } catch {
+      return false
+    }
+  }
+
+  private holds(c: WaitCondition, frames: PageFrame[]): Promise<boolean | string> {
+    return conditionHolds(this.frames, frames, c, (handle) => this.isShown(handle))
+  }
+
+  /** Wait until the condition holds, bounded: network idle first, then the rest every 200 ms. */
+  async waitFor(c: WaitCondition, timeoutMs: number): Promise<{ met: boolean; waitedMs: number; error?: string }> {
+    const start = Date.now()
+    const deadline = start + timeoutMs
+    if (c.networkIdle) {
+      const quiet = await this.settle(timeoutMs, 500)
+      if (!quiet) return { met: false, waitedMs: Date.now() - start }
+    }
+    const rest = c.text !== undefined || c.textGone !== undefined || c.selector !== undefined || c.ref !== undefined
+    if (!rest) return { met: true, waitedMs: Date.now() - start }
+    // Text and selectors are looked for in every frame (an App embedded in Studio), found again now and then.
+    const scan = c.text !== undefined || c.textGone !== undefined || c.selector !== undefined
+    let frames: PageFrame[] = scan ? await this.frames.all() : [this.frames.main]
+    let found = Date.now()
+    for (;;) {
+      if (this.dialog) return { met: false, waitedMs: Date.now() - start }
+      if (scan && Date.now() - found > FRAMES_AGAIN_MS) {
+        frames = await this.frames.all()
+        found = Date.now()
+      }
+      const h = await this.holds(c, frames)
+      if (typeof h === 'string') return { met: false, waitedMs: Date.now() - start, error: h }
+      if (h) return { met: true, waitedMs: Date.now() - start }
+      if (Date.now() >= deadline || !this.alive) return { met: false, waitedMs: Date.now() - start }
+      await sleep(200)
+    }
+  }
+
+  /** Run an input the page may answer with a dialog: it returns when the input is done, or as soon as a dialog opens. */
+  private async unlessDialog(action: () => Promise<void>): Promise<void> {
+    if (this.dialog) return
+    let wake: () => void = () => {}
+    const opened = new Promise<'dialog'>((r) => {
+      wake = () => r('dialog')
+    })
+    this.dialogWaiters.add(wake)
+    const run = action().then(
+      () => null,
+      (err: Error) => err,
+    )
+    try {
+      const first = await Promise.race([run, opened])
+      if (first instanceof Error && !this.dialog) throw first
+    } finally {
+      this.dialogWaiters.delete(wake)
+    }
+  }
+
+  async answerDialog(accept: boolean, promptText?: string): Promise<void> {
+    const d = this.pendingDialog
+    if (!d) throw new Error('no dialog is open')
+    if (accept) await d.accept(promptText)
+    else await d.dismiss()
+    this.pendingDialog = null
+    this.dialog = null
+  }
+
+  /** The middle of an element on screen, scrolled into view (with the frames it is in). */
+  center(handle: number): Promise<{ x: number; y: number }> {
+    return this.frames.center(handle)
+  }
+
+  async click(backendNodeId: number, opts: { double?: boolean; button?: 'left' | 'right' | 'middle' } = {}): Promise<void> {
+    const at = await this.center(backendNodeId)
+    const button = opts.button ?? 'left'
+    await this.unlessDialog(async () => {
+      await this.cdp('Input.dispatchMouseEvent', { type: 'mouseMoved', x: at.x, y: at.y })
+      for (let n = 1; n <= (opts.double ? 2 : 1); n++) {
+        await this.cdp('Input.dispatchMouseEvent', { type: 'mousePressed', x: at.x, y: at.y, button, clickCount: n })
+        await this.cdp('Input.dispatchMouseEvent', { type: 'mouseReleased', x: at.x, y: at.y, button, clickCount: n })
+      }
+    })
+  }
+
+  async hover(backendNodeId: number): Promise<void> {
+    const at = await this.center(backendNodeId)
+    await this.cdp('Input.dispatchMouseEvent', { type: 'mouseMoved', x: at.x, y: at.y })
+  }
+
+  async pressKey(press: KeyPress, backendNodeId?: number): Promise<void> {
+    if (backendNodeId !== undefined) {
+      await this.center(backendNodeId).catch(() => null)
+      await this.frames.focus(backendNodeId, FOCUS)
+    }
+    await this.unlessDialog(async () => {
+      const base = { key: press.key, code: press.code, windowsVirtualKeyCode: press.keyCode, nativeVirtualKeyCode: press.keyCode, modifiers: press.modifiers }
+      await this.cdp('Input.dispatchKeyEvent', { type: press.text ? 'keyDown' : 'rawKeyDown', ...base, ...(press.text ? { text: press.text, unmodifiedText: press.text } : {}) })
+      await this.cdp('Input.dispatchKeyEvent', { type: 'keyUp', ...base })
+    })
+  }
+
+  async selectOptions(backendNodeId: number, values: string[]): Promise<{ values: string[] } | { error: string }> {
+    await this.center(backendNodeId).catch(() => null)
+    return (await this.callOn<{ values: string[] } | { error: string }>(backendNodeId, SELECT_OPTIONS, [values])) ?? { error: 'the page did not answer' }
+  }
+
+  /**
+   * The agent's expression, in the page's own world (where the App's state
+   * lives), bounded in time. With an element (its handle), in the world of
+   * the frame it is in, a function called with the element.
+   */
+  async evaluateInPage(expression: string, cap: number, timeoutMs = 10_000, handle?: number): Promise<{ type: string; json: string; length: number } | { error: string }> {
+    type Evaluated = { result: { value?: { type: string; json: string; length: number } }; exceptionDetails?: { text?: string; exception?: { description?: string } } }
+    const box: { res: Evaluated | null } = { res: null }
+    await this.unlessDialog(async () => {
+      const run = async (): Promise<Evaluated> => {
+        if (handle === undefined) return this.cdp<Evaluated>('Runtime.evaluate', { expression: evaluateWrapper(expression, cap), returnByValue: true, awaitPromise: true, userGesture: false, timeout: timeoutMs })
+        const { frame, node } = this.frames.locate(handle)
+        const resolved = await frame.cdp<{ object: { objectId?: string } }>('DOM.resolveNode', { backendNodeId: node })
+        if (!resolved.object.objectId) throw new Error('the element is gone: take a new browser_snapshot')
+        return frame.cdp<Evaluated>('Runtime.callFunctionOn', { objectId: resolved.object.objectId, functionDeclaration: evaluateOnElement(expression, cap), returnByValue: true, awaitPromise: true, userGesture: false })
+      }
+      box.res = await Promise.race([run().catch((err: Error) => ({ result: {}, exceptionDetails: { text: err.message } }) as Evaluated), sleep(timeoutMs + 1_000).then(() => null)])
+    })
+    if (this.dialog) return { error: 'it opened a dialog' }
+    const res = box.res
+    if (!res) return { error: `it did not finish within ${timeoutMs / 1000} seconds` }
+    if (res.exceptionDetails) return { error: (res.exceptionDetails.exception?.description ?? res.exceptionDetails.text ?? 'it threw').slice(0, 2_000) }
+    return res.result.value ?? { error: 'it answered nothing the page could send back' }
+  }
+
+  async isPassword(handle: number): Promise<boolean> {
+    const { frame, node: backendNodeId } = this.frames.locate(handle)
+    const { node } = await frame.cdp<{ node: { attributes?: string[] } }>('DOM.describeNode', { backendNodeId })
+    const attrs = node.attributes ?? []
+    for (let i = 0; i < attrs.length; i += 2) if (attrs[i] === 'type' && attrs[i + 1]?.toLowerCase() === 'password') return true
+    return attrs.some((a, i) => i % 2 === 0 && a === 'autocomplete' && /password/i.test(attrs[i + 1] ?? ''))
+  }
+
+  async type(backendNodeId: number, text: string, opts: { clear: boolean; submit: boolean }): Promise<void> {
+    await this.center(backendNodeId).catch(() => null)
+    await this.unlessDialog(async () => {
+      await this.frames.focus(backendNodeId, opts.clear ? SELECT_CONTENTS : CARET_TO_END)
+      await this.cdp('Input.insertText', { text })
+      if (opts.submit) {
+        await this.cdp('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, text: '\r' })
+        await this.cdp('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 })
+      }
+    })
+  }
+
+  async setSize(size: { device: DeviceWidth } | { width: number; height: number | null }): Promise<void> {
+    if ('device' in size) {
+      this.device = size.device
+      this.viewport = null
+      const d = DEVICE_SIZES[size.device]
+      await this.page.setViewportSize({ width: d.width, height: d.height })
+    } else {
+      this.device = 'desktop'
+      this.viewport = size
+      await this.page.setViewportSize({ width: size.width, height: size.height ?? this.page.viewportSize()?.height ?? DEVICE_SIZES.desktop.height })
+    }
+  }
+
+  async viewportWidth(): Promise<number> {
+    const m = await this.cdp<{ cssLayoutViewport?: { clientWidth: number } }>('Page.getLayoutMetrics').catch(() => null)
+    return m?.cssLayoutViewport?.clientWidth ?? this.page.viewportSize()?.width ?? 0
+  }
+
+  /** A PNG, base64; a dialog holds the page, so the capture goes through DevTools rather than wait for it. */
+  async screenshot(opts: { fullPage?: boolean } = {}): Promise<string> {
+    if (opts.fullPage) {
+      const metrics = await this.cdp<{ cssContentSize: { width: number; height: number } }>('Page.getLayoutMetrics')
+      const { width, height } = metrics.cssContentSize
+      const { data } = await this.cdp<{ data: string }>('Page.captureScreenshot', { format: 'png', clip: { x: 0, y: 0, width: Math.ceil(width), height: Math.min(Math.ceil(height), 16_000), scale: 1 }, captureBeyondViewport: true })
+      return data
+    }
+    const { data } = await this.cdp<{ data: string }>('Page.captureScreenshot', { format: 'png' })
+    return data
+  }
+
+  pageText(): Promise<string | null> {
+    return this.evaluate<string>(PAGE_TEXT)
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+    for (const { session } of this.frameSessions.values()) void session.detach().catch(() => {})
+    this.frameSessions.clear()
+    // A page waiting on a dialog closes only once it is answered.
+    await this.pendingDialog?.dismiss().catch(() => {})
+    await this.page.close().catch(() => {})
+  }
+}

package/src/mcp/browser/keys.ts

@@ -0,0 +1,70 @@
+/**
+ * A key the agent presses (`browser_press_key`), as the DevTools Protocol's
+ * `Input.dispatchKeyEvent` takes it. Names follow Playwright's: `Enter`,
+ * `ArrowDown`, `a`, and combinations such as `Shift+Tab` or `Meta+a`.
+ * Shared by Forge's Browser and the headless one `frontera mcp` runs.
+ */
+
+export interface KeyPress {
+  key: string
+  code: string
+  keyCode: number
+  /** What the key types; none for a key that only moves or edits, or with Control, Alt or Meta held. */
+  text?: string
+  /** Alt 1, Control 2, Meta 4, Shift 8. */
+  modifiers: number
+}
+
+const NAMED: Record<string, { code: string; keyCode: number; text?: string }> = {
+  Enter: { code: 'Enter', keyCode: 13, text: '\r' },
+  Tab: { code: 'Tab', keyCode: 9 },
+  Escape: { code: 'Escape', keyCode: 27 },
+  Backspace: { code: 'Backspace', keyCode: 8 },
+  Delete: { code: 'Delete', keyCode: 46 },
+  Space: { code: 'Space', keyCode: 32, text: ' ' },
+  ArrowUp: { code: 'ArrowUp', keyCode: 38 },
+  ArrowDown: { code: 'ArrowDown', keyCode: 40 },
+  ArrowLeft: { code: 'ArrowLeft', keyCode: 37 },
+  ArrowRight: { code: 'ArrowRight', keyCode: 39 },
+  Home: { code: 'Home', keyCode: 36 },
+  End: { code: 'End', keyCode: 35 },
+  PageUp: { code: 'PageUp', keyCode: 33 },
+  PageDown: { code: 'PageDown', keyCode: 34 },
+  Insert: { code: 'Insert', keyCode: 45 },
+  ...Object.fromEntries(Array.from({ length: 12 }, (_, i) => [`F${i + 1}`, { code: `F${i + 1}`, keyCode: 112 + i }])),
+}
+
+const ALIASES: Record<string, string> = { Esc: 'Escape', Return: 'Enter', Up: 'ArrowUp', Down: 'ArrowDown', Left: 'ArrowLeft', Right: 'ArrowRight', Del: 'Delete', ' ': 'Space' }
+
+const MODIFIERS: Record<string, number> = { Alt: 1, Option: 1, Control: 2, Ctrl: 2, Meta: 4, Command: 4, Cmd: 4, Shift: 8 }
+
+const PUNCTUATION: Record<string, { code: string; keyCode: number }> = {
+  '-': { code: 'Minus', keyCode: 189 }, '=': { code: 'Equal', keyCode: 187 }, '[': { code: 'BracketLeft', keyCode: 219 }, ']': { code: 'BracketRight', keyCode: 221 },
+  '\\': { code: 'Backslash', keyCode: 220 }, ';': { code: 'Semicolon', keyCode: 186 }, "'": { code: 'Quote', keyCode: 222 }, ',': { code: 'Comma', keyCode: 188 },
+  '.': { code: 'Period', keyCode: 190 }, '/': { code: 'Slash', keyCode: 191 }, '`': { code: 'Backquote', keyCode: 192 },
+}
+
+/** The key event for a name, or why it is not one. */
+export function parseKey(name: string): KeyPress | { error: string } {
+  const raw = name.trim()
+  if (!raw) return { error: 'key is required, e.g. Enter, Escape, ArrowDown, a or Shift+Tab.' }
+  // `+` alone, or as the last part (`Shift++`), is the plus key.
+  const parts = raw === '+' ? ['+'] : raw.endsWith('++') ? [...raw.slice(0, -2).split('+'), '+'] : raw.split('+')
+  const last = parts.pop()!
+  let modifiers = 0
+  for (const p of parts) {
+    const m = MODIFIERS[p.trim()]
+    if (m === undefined) return { error: `"${p}" is not a modifier: use Shift, Control, Alt or Meta.` }
+    modifiers |= m
+  }
+  const keyName = ALIASES[last] ?? last
+  const named = NAMED[keyName]
+  const typing = (modifiers & ~8) === 0
+  if (named) return { key: keyName === 'Space' ? ' ' : keyName, code: named.code, keyCode: named.keyCode, ...(named.text && typing ? { text: named.text } : {}), modifiers }
+  if ([...keyName].length !== 1) return { error: `Unknown key "${last}": use a name such as Enter, Tab, Escape, Backspace, ArrowDown, Home, PageDown or F5, or a single character.` }
+  const shift = (modifiers & 8) !== 0
+  const char = /^[a-z]$/i.test(keyName) ? (shift ? keyName.toUpperCase() : keyName) : keyName
+  const code = /^[a-z]$/i.test(keyName) ? `Key${keyName.toUpperCase()}` : /^\d$/.test(keyName) ? `Digit${keyName}` : (PUNCTUATION[keyName]?.code ?? '')
+  const keyCode = /^[a-z0-9]$/i.test(keyName) ? keyName.toUpperCase().charCodeAt(0) : (PUNCTUATION[keyName]?.keyCode ?? 0)
+  return { key: char, code, keyCode, ...(typing ? { text: char } : {}), modifiers }
+}