Metadata-Version: 2.4
Name: helixwright
Version: 0.1.6
Summary: Python automation SDK for Helix Browser Local API and the private Helix RPC page-control plane.
Author: Helix Browser
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://pypi.org/project/helixwright/
Project-URL: Documentation, https://pypi.org/project/helixwright/
Keywords: automation,browser,fingerprint,chromium,local-api,helix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Helixwright

Helixwright is the Python automation SDK for Helix Browser.

It does not create fingerprints locally, manage browser profile folders, or
start `chrome.exe` directly. Profile creation, fingerprint generation, proxy
configuration, browser launch, and profile sync are delegated to Helix Browser
Desktop through its Local API. Page actions then use the private Helix RPC
control plane built into the Helix Chromium fork, not CDP, DevTools, WebDriver,
Playwright, or Selenium.

## Install

```bash
pip install helixwright
```

Requirements:

1. Helix Browser Desktop is installed and running.
2. The desktop app is logged in.
3. The desktop Local API is available, usually at `http://127.0.0.1:59777`.
4. The desktop build supports `/api/v1/automation/sessions`.

Helixwright discovers the Local API from:

```text
%APPDATA%\Helix Browser\local_api.json
%APPDATA%\fpclient\local_api.json
```

The first path is the preferred Helix config directory. The `fpclient` path is
kept for existing local installations that still use the legacy config
directory.

You can override it explicitly:

```powershell
$env:HELIX_LOCAL_API = "http://127.0.0.1:59777"
```

## Quick Start

Reuse an existing Helix profile:

```python
import helixwright as hw

with hw.launch(profile_id="profile_123", url="https://example.com") as page:
    page.ele("#email").input("user@example.com")
    page.ele("#submit").click()
```

Create or reuse a profile by `account_id`:

```python
import helixwright as hw

with hw.launch(
    "https://example.com",
    account_id="shop-001",
    name="Shop 001",
    proxy="http://user:pass@127.0.0.1:7890",
    fingerprint=hw.Fingerprint(locale="en-US", region="US", group="octo"),
    update_existing=True,
) as page:
    page.wait_for("body", timeout=10_000)
    print(page.title())
```

Use a reusable launch config:

```python
import helixwright as hw

cfg = hw.LaunchConfig(
    account_id="shop-002",
    name="Shop 002",
    url="https://example.com",
    start_pages=["https://example.com", "https://example.com/login"],
    proxy="http://127.0.0.1:7890",
    fingerprint=hw.Fingerprint(locale="en-US", region="US"),
    update_existing=True,
)

with hw.launch(config=cfg) as page:
    page.ele("text=Login").click()
```

## Client API

Use `Client` when you want to manage profiles, fingerprints, proxies, cores, or
automation sessions explicitly:

```python
import helixwright as hw

client = hw.Client()
print(client.health())
print(client.session())

profile = client.profiles.ensure(
    account_id="shop-003",
    name="Shop 003",
    proxy=hw.Proxy("http", "127.0.0.1", 7890),
    fingerprint=hw.Fingerprint(locale="en-US", region="US"),
    update_existing=True,
)

with profile.launch(url="https://example.com") as page:
    print(page.url)
```

Common managers:

```python
client.profiles.list(page=1, size=20)
client.profiles.get("profile_123")
client.profiles.create(name="A", account_id="acct_A")
client.profiles.ensure(account_id="acct_A")
client.profiles.clone("profile_123", count=2)
client.profiles.sync_up("profile_123")
client.profiles.sync_down("profile_123")

client.fingerprint.options()
client.fingerprint.draw(account_id="acct_A", group="octo")
client.fingerprint.serialize({"ua": "..."}, seed=123)
client.fingerprint.redraw({"ua": "..."}, "ua")

client.proxy.check("http://127.0.0.1:7890")
client.cores.list()
client.cores.ensure("chromium", "149.0.7827.156")
client.browser.active()
client.browser.start("profile_123")
client.browser.stop("profile_123")
client.browser.stop_all()
client.automation.list()
client.automation.start("profile_123", url="https://example.com")
client.automation.stop("auto_123")
```

## RPC Metadata And Input Receipts

Normal scripts can keep using `page.ele(...)`, navigation, trace, and network
helpers. For diagnostics and multi-target workflows, the operator exposes the
browser RPC metadata layer when the installed core supports it:

```python
print(page.rpc_hello())
print(page.rpc_endpoint_path)
print(page.rpc_describe())
print(page.rpc_ping())
print(page.targets())
page.activate_target(index=0)
print(page.frame_context())
print(page.last_action_receipt())
```

The current cloud-active M149 core is RPC V3: `rpc.hello` advertises protocol
version 3, action receipts, typed errors, method metadata, and preferred
endpoint `/rpc/v2`. Helixwright probes `/rpc` first for compatibility, then
switches to the preferred endpoint reported by `rpc.hello`.

The SDK also supports the V4 source contract being staged in the M149 browser
tree: protocol version 4, preferred endpoint `/rpc/v3`, explicit request
context, and unified `input.action`. When a V4 core advertises
`input_action_vm`, Helixwright sends keyboard, mouse, wheel, drag, and text
actions through `input.action`; otherwise it falls back to the V3 atomic input
methods or older RPC methods.

Older V2/V1 cores still attach. V2 uses `/rpc/v1`; V1 uses legacy `/rpc`.
`rpc_hello()` falls back to a V1 capability payload when the browser does not
expose `rpc.hello`.

## Native Trace

Native trace records the page timeline locally through the Helix browser core:
RPC actions, navigation, network metadata, console messages, and native DOM
snapshots. It does not use CDP, WebDriver, Playwright, Selenium, or page-world
JavaScript.

Local API is only used to start the automation session and return the browser
RPC endpoint. All trace calls below go directly from Helixwright to the browser
RPC endpoint; they are not forwarded through Local API.

Default mode is summary. Use `full=True` only when you need full DOM snapshot
payloads for debugging or AI code generation. Trace data is not redacted.

```python
import helixwright as hw

with hw.launch("https://example.com/login", account_id="trace-demo") as page:
    page.trace_start()  # summary mode

    page.trace_action(
        "fill-login",
        lambda: page.ele("#email").input("user@example.com"),
        settle_ms=800,
    )

    state = page.where_am_i({
        "login": lambda p: p.ele("#email").exists(),
        "dashboard": lambda p: "/dashboard" in p.url,
        "blocked": lambda p: p.ele(text="Verify").exists(),
    })

    page.trace_export("trace-login.json")
    print("state:", state)
```

Full trace:

```python
page.trace_start(full=True)
page.trace_snapshot(full=True)
page.trace_export("trace-full.json")
```

CLI capture for an already-running automation session:

```powershell
python -m helixwright trace --session auto_123 --duration 15 --output trace.json
python -m helixwright trace --session auto_123 --full --duration 15 --output trace-full.json
```

## Launch Rules

`hw.launch()` requires either `profile_id` or `account_id`/`account`.

Important behavior:

- `profile_id` means reuse that exact Helix profile.
- `account_id` means find an existing profile by account ID, or create one
  when `create=True`.
- `fingerprint=hw.Fingerprint(...)` only sends creation hints to Helix Local
  API. The SDK does not generate fingerprints itself.
- `proxy` can be a string, dict, or `hw.Proxy`.
- `start_pages` is passed to the Local API automation session.
- `config=hw.LaunchConfig(...)` should not be mixed with explicit
  `profile_id`, `account_id`, `name`, `proxy`, or `fingerprint` arguments.
- `page.close()` stops the Local API automation session, waits until that
  session disappears, then waits until the matching `/browser/active` entry is
  gone before returning. Browser cleanup errors are propagated instead of being
  silently ignored.

Unsupported legacy direct-launch arguments are rejected, including `chrome`,
`user_data_dir`, `persona`, `seed`, `geoip`, and `extra_args`.

## Errors

Common error types:

| Error | Meaning |
| --- | --- |
| `LocalApiUnavailable` | Helix Desktop is not running, the Local API address is wrong, or the port is unreachable. |
| `DesktopNotLoggedIn` | Desktop is reachable but not logged in. |
| `LocalApiError` | Local API returned a business error. |
| `ProfileNotFound` | The requested profile does not exist. |
| `AutomationEndpointUnavailable` | The desktop build did not return a usable automation RPC endpoint. |
| `AutomationSessionNotFound` | The requested automation session does not exist. |
| `RpcError` | The browser RPC endpoint returned a structured RPC error with a `code`. |
| `TransportError` | The private page RPC connection failed, usually because the browser exited. |
| `WaitTimeoutError` | A page wait condition timed out. |

## Examples

From the source repository:

```powershell
cd "E:\Helix Browser\repos\helixwright"
python examples\99_offline_mock_demo.py
```

The offline demo does not need Helix Browser. It starts a mock Local API and
mock RPC endpoint, then exercises the public SDK surface.

Real desktop examples require Helix Browser Desktop to be running and logged in:

```powershell
python examples\00_helixwright_quickstart.py
python examples\01_client_managers.py
python examples\02_launch_config_and_actions.py
```

Useful environment variables:

```powershell
$env:HELIX_LOCAL_API = "http://127.0.0.1:59777"
$env:HELIX_EXAMPLE_ACCOUNT = "demo-account"
$env:HELIX_EXAMPLE_URL = "https://example.com"
$env:HELIX_EXAMPLE_PROXY = "http://127.0.0.1:7890"
$env:HELIX_EXAMPLE_TIMEOUT_MS = "30000"
```

## Development

```powershell
cd "E:\Helix Browser\repos\helixwright"
pip install -e .
python tests\ci.py
```

Build and validate a distribution:

```powershell
python -m build
python -m twine check dist/*
```

## Boundary

Helixwright is only the automation SDK. The authoritative source for profiles,
fingerprints, proxies, browser core downloads, cloud sync, and launch lifecycle
is Helix Browser Desktop plus its Local API.
