# Browser Context & Locator Pack for AI Agents (`produkdigitalali/browser-context-locator-pack`) Actor

Turn public web pages into bounded context JSON and verified Playwright locator candidates. Inspect links, buttons and form controls without an AI API key.

- **URL**: https://apify.com/produkdigitalali/browser-context-locator-pack.md
- **Developed by:** [ProdukDigitalAli](https://apify.com/produkdigitalali) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$8.00 / 1,000 browser context pack createds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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

```json
{"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:

```json
{"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.

# Changelog

This Actor's version history is a separate document: https://apify.com/produkdigitalali/browser-context-locator-pack/changelog.md

# Actor input Schema

## `urls` (type: `array`):

One to three public pages, deduplicated. No login sessions. Results contain public page text: review privacy before use.

## `maxElements` (type: `integer`):

Bounded visible control candidates; over-cap captures report truncation.

## `maxOutputBytes` (type: `integer`):

UTF-8 JSON byte budget per READY result, not a token budget.

## `settleMs` (type: `integer`):

Wait briefly after DOM readiness before capture.

## `navigationTimeoutSeconds` (type: `integer`):

Maximum wait for initial navigation.

## Actor input object example

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

# Actor output Schema

## `summary` (type: `string`):

No description

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://example.com/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("produkdigitalali/browser-context-locator-pack").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "urls": ["https://example.com/"] }

# Run the Actor and wait for it to finish
run = client.actor("produkdigitalali/browser-context-locator-pack").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://example.com/"
  ]
}' |
apify call produkdigitalali/browser-context-locator-pack --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,produkdigitalali/browser-context-locator-pack"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7w8xUZdDRYQxnolBc/builds/6VnKNYgB582TpHBgJ/openapi.json