Metadata-Version: 2.4
Name: helixwright
Version: 2.0.0
Summary: Direct-to-kernel automation SDK for the Helix Browser v5 loopback RPC endpoint
Author: Helix Browser
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://pypi.org/project/helixwright/
Project-URL: Documentation, https://66.154.125.146/helixwright/
Keywords: automation,browser,fingerprint,chromium,helix,rpc
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# helixwright

Direct-to-kernel automation SDK for the Helix Browser v5 loopback RPC endpoint.

中文：Helix 内核 v5 环回端点的直连自动化 SDK。

`helixwright` drives a Helix Browser kernel (a patched Chromium) over its private
loopback RPC endpoint. It speaks the `helix-rpc-v5` envelope on `/rpc/v5` and
exposes all **86** contract methods.

**There is no client process in the link.** The SDK reads a discovery file to get
`{port, token}` and talks to the kernel directly, so a full session runs on a CI
worker, a container, or a headless server with no GUI client installed. It also
means the endpoint itself is the security boundary.

- Zero third-party dependencies — standard library only.
- Python 3.12+
- Windows x64 (the only kernel build target)
- Kernel: Chromium 149.0.7827.156

## Install

```
pip install helixwright
```

## Launch a kernel and drive it

The SDK starts and reclaims the browser itself. Nothing else needs to be running.

```python
from helixwright import KernelLauncher
from helixwright.launch import RECOMMENDED_UNATTENDED_ARGS

launcher = KernelLauncher(
    r"C:\path\to\HelixBrowser\Chrome-bin\chrome.exe",
    r"C:\path\to\profile",                      # user-data-dir
    extra_args=list(RECOMMENDED_UNATTENDED_ARGS),
)

with launcher.launch() as kernel:
    c = kernel.client
    c.methods.navigate(url="https://example.com")
    c.methods.wait_for_load(timeout_ms=10000)
    print(c.methods.current_url()["url"])
    c.methods.element.action(selector="#login", action="click")
```

`launch()` judges readiness in three separate stages — process alive, endpoint
advertised, handshake accepted — each with its own budget and its own failure
reason, so a failure tells you *which* stage broke instead of just "timed out".
`close()` runs a graceful-then-forced reclaim ladder and reports orphans
explicitly rather than leaving them silently behind.

The launcher synthesises two switches because without them the kernel fails
*silently*: `--user-data-dir` (no endpoint is started without it) and
`--helix-automation` (the control-plane gate). Everything else — persona, proxy,
window size — is passed through verbatim; those are client-side domain knowledge
and this SDK does not invent them.

## Attach to a kernel that is already running

```python
from helixwright import Client

with Client.connect(user_data_dir=r"C:\path\to\profile") as c:
    c.methods.navigate(url="https://example.com")
```

## Calling methods

`c.methods.<name>(...)` and `c.call("<name>", {...})` are the same thing.
Dotted contract names are attribute paths: `element.action` is
`c.methods.element.action(...)`.

Parameters are checked before the request leaves the process. This matters more
than usual here: the kernel reads missing or wrongly-typed parameters as
`value_or(zero)` and does **not** report an error, so `mouse_move(x="100")`
would silently move the pointer to `(0, 0)`. The SDK carries a parameter table
measured against the patch stack and refuses the call instead.

```python
from helixwright import describe, validate

describe("mouse_move")           # required params, types, hard enums
validate("mouse_move", {"x": 100, "y": 250})
```

Anything the kernel would clamp or zero-fill silently is surfaced on
`client.notices`.

## Things worth knowing

- **No push channel.** The kernel closes WebSocket upgrades. Event-style methods
  are polled; there are no subscriptions.
- **A 404 is ambiguous** — a bad token, an unaccepted path, and a port taken by
  another process all look identical. The SDK stops on 404 rather than retrying
  with a different token or path, because retrying a different path would turn an
  authentication failure into a silent protocol downgrade.
- **Returning `ok` is not the same as working.** `cursor_overlay(on=True)`
  answers `ok` with `mode="off"` when the kernel was started without
  `--helix-virtual-cursor`. Check the verdict, not the exception.
- **Pointer actions are asynchronous and single-flight.** The RPC returns before
  the humanised trajectory has finished, and issuing the next pointer action
  truncates the one still in flight.

## Support

This is proprietary software distributed for use with Helix Browser. It is not
open source and carries no warranty.
