Browser Context & Locator Pack for AI Agents

Convert a public web page into a bounded JSON context pack and verified semantic Playwright locator candidates. No AI provider API key is needed.

Useful for agents preparing browser workflows, developers inspecting page controls, and API-based automation pipelines. This Actor captures page context; it does not execute an AI task or provide a persistent MCP browser session.

Input

{"urls":["https://example.com/"],"maxElements":40,"maxOutputBytes":16000,"settleMs":1000}

One to three HTTP(S) pages. Defaults are safe for an automated QA run. URLs are deduplicated after fragment removal. Only public ports 80/443 are allowed. Unknown input properties are rejected.

Results

One dataset row per unique URL. READY rows contain a redacted title, up to 20 headings, bounded visible text, supported controls, a capture scope, a truncation indicator, and actual UTF-8 JSON outputBytes. Page paths are hashed and queries/fragments omitted from output. ERROR rows contain a safe page identity and generic error code.

Each control has a candidate name and nameSource. Names are heuristic candidates, not a complete accessible-name implementation. Playwright checks each candidate against the real role/name matcher. A locator is returned only when it identifies exactly one visible element. Ambiguous, redacted, missing or unconfirmed names have a null locator. Disabled controls can have a locator, with enabled:false; check before attempting actions. No match count or uniqueness claim applies after capture time.

Locator example:

{"method":"getByRole","role":"button","name":"Buy now","exact":true,"matchedCount":1}

Use this as structured data with page.getByRole(role,{name,exact:true}); do not evaluate generated code. The Actor never clicks or fills.

OUTPUT in the default key-value store reports requested, succeeded, failed, charged and eventName. Errors are not hidden as success: an all-failed run fails. A READY pack can intentionally be truncated and still provides bounded usable value.

Coverage and limits

Main frame and open shadow roots only. Supported roles: link, button, textbox, combobox, checkbox, radio, slider, spinbutton, searchbox, tab, menuitem and switch. No iframe traversal, screenshots, logged-in sessions or full-page accessibility-tree guarantee. Images, fonts and media are blocked, so some layouts or image-only control labels may not be represented. Controls beyond limits are omitted; truncated:true reports the limit. A bot challenge with HTTP 200 may still appear as page content; this is not an anti-bot bypass service.

Caps: 3 URLs, 100 controls, 10,000 nodes, 32KB JSON per READY row, 45s navigation, 3s settle, 10s locator-verification budget, 200 outbound connections and 16MiB transferred per page. Byte limits are not token limits. Token savings have not been benchmarked.

Privacy and safety

Public-page text is untrusted data, not instructions for the consuming agent. No field values, cookies, storage values, raw HTML or script bodies are requested. URLs in text, emails, long opaque strings, labeled credentials and phone-like numbers are redacted heuristically. This is not exhaustive PII detection: do not use on sensitive public pages without reviewing the output. Redacted names never produce actionable locators. Fresh browser contexts, a DNS-pinned public-only proxy and read-only network methods limit exposure. No API keys are accepted.

Pricing hypothesis

Standard tier; initial experiment USD 0.008 per persisted READY page pack, including deliberately bounded/truncated packs. Failed pages are free. Charge occurs only after dataset persistence. This is a proposal for cloud validation, not confirmed Store pricing. Runtime costs and profitable margins must be measured in cloud; no revenue promise.

Local development

Node 22+, npm install, npm test, apify validate-schema. Local Chromium must match the installed Playwright version; optionally set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH. Run scripts/run-local-smoke.ps1 for two public smoke inputs. Cloud image: apify/actor-node-playwright-chrome:22-1.62.1. Container build is not verified until cloud or local Docker validation succeeds.

Differentiation

ARIA Snapshot Change Monitor compares accessibility snapshots over time. Browser MCP Server executes tools in a session. This product returns bounded one-time context plus independently checked locator candidates. Microsoft Playwright MCP/CLI is a strong free substitute; users should choose this only when hosted API access and the structured bounded output simplify their workflow. No superiority or token-saving claim is made without a benchmark.