Metadata-Version: 2.4
Name: rom-runtime
Version: 0.0.8
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Summary: Python wrapper for the ROM browser-like runtime
Keywords: rom,runtime,browser,web-api,fingerprint
Home-Page: https://github.com/Rxflex/rom
Author: Rxflex
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Rxflex/rom
Project-URL: Issues, https://github.com/Rxflex/rom/issues
Project-URL: Repository, https://github.com/Rxflex/rom

# `rom-runtime`

Python bindings for the ROM browser-like runtime.

This package exposes a thin Python API on top of ROM:

- `eval()`
- `eval_async()`
- `eval_json()`
- `surface_snapshot()`
- `fingerprint_probe()`
- `run_fingerprintjs_harness()`
- `fingerprintjs_version()`

It prefers a native `PyO3` extension when available and falls back to the ROM CLI bridge otherwise.

## Install

```bash
pip install rom-runtime
```

## Usage

```python
from rom import RomRuntime, has_native_binding

runtime = RomRuntime(
    {
        "href": "https://example.test/",
        "referrer": "https://referrer.example/",
        "cors_enabled": False,
        "proxy_url": None,
    }
)
href = runtime.eval_async("(async () => location.href)()")
snapshot = runtime.surface_snapshot()

print("native:", has_native_binding())
print(href)
print(snapshot["fetch"])

runtime.eval_async("(async () => { globalThis.__rom_value = 42; return 'ok'; })()")
print(runtime.eval_async("(async () => String(globalThis.__rom_value))()"))
```

Config keys use the Rust runtime field names, so use snake_case such as `cors_enabled` and `proxy_url`.
`cors_enabled` is `False` by default.
When the native extension is loaded, one `RomRuntime` instance keeps JS globals alive across multiple `eval()` and `eval_async()` calls.

## Optional native build from source

```bash
python -m pip install maturin
python -m maturin build --manifest-path bindings/gom-python/Cargo.toml --release
```

Tagged GitHub releases build and publish wheels for Linux, Windows, and macOS, plus an sdist for source installs.

## Common methods

- `eval()`
- `eval_async()`
- `eval_json()`
- `surface_snapshot()`
- `fingerprint_probe()`
- `run_fingerprintjs_harness()`
- `fingerprintjs_version()`

## Environment

- `ROM_FORCE_CLI_BRIDGE=1`: disable the native path and force CLI fallback
- `ROM_BRIDGE_BIN`: explicit path to the `rom_bridge` executable
- `ROM_BRIDGE_CWD`: working directory used by the CLI fallback

## More docs

- Root guide: [../../README.md](../../README.md)
- LLM guide: [../../LLMS.md](../../LLMS.md)

