npm package: @rxflex/rom
Description: Node.js wrapper for the ROM browser-like runtime
Author: Rxflex
Latest version: 0.0.20

# `@rxflex/rom`

Node.js bindings for the ROM browser-like runtime.

This package exposes a small JavaScript API on top of ROM:

- `eval()`
- `evalAsync()`
- `evalJson()`
- `goto()`
- `setContent()`
- `content()`
- `evaluate()`
- `waitForSelector()`
- `waitForFunction()`
- `click()`
- `fill()`
- `textContent()`
- `innerHTML()`
- `locator()`
- `surfaceSnapshot()`
- `fingerprintProbe()`
- `runFingerprintJsHarness()`
- `fingerprintJsVersion()`

It prefers a native `napi-rs` bridge when available and falls back to the ROM CLI bridge otherwise.

## Install

```bash
npm install @rxflex/rom
```

## Usage

```js
import { RomRuntime, hasNativeBinding } from "@rxflex/rom";

const runtime = new RomRuntime({
  href: "https://example.test/",
  referrer: "https://referrer.example/",
  cors_enabled: false,
  proxy_url: process.env.ROM_PROXY_URL ?? null,
});

const href = await runtime.evalAsync("(async () => location.href)()");
const snapshot = await runtime.surfaceSnapshot();

console.log("native:", hasNativeBinding());
console.log(href);
console.log(snapshot.fetch);

await runtime.evalAsync("(async () => { globalThis.__romValue = 42; return 'ok'; })()");
console.log(await runtime.evalAsync("(async () => String(globalThis.__romValue))()"));

await runtime.setContent(
  '<div id="app"><input id="name" /><button id="go">Go</button><span id="out"></span></div>' +
    '<script>document.querySelector("#go").addEventListener("click",()=>{document.querySelector("#out").textContent=document.querySelector("#name").value;});</script>',
);
await runtime.fill("#name", "ROM");
await runtime.click("#go");
console.log(await runtime.textContent("#out"));
```

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 addon is loaded, one `RomRuntime` instance keeps JS globals alive across multiple `eval()` and `evalAsync()` calls.
The page-like helpers such as `goto()`, `setContent()`, `click()`, and `waitForSelector()` require the native binding because CLI bridge mode is stateless across calls.
For cookie seeding, the wrapper accepts either serialized `cookie_store`, a raw cookie header string such as `"api_uid=seeded; _nano_fp=abc"`, or a `cookies` alias with string/object/array inputs.
For storage seeding, the wrapper accepts `local_storage` and `session_storage` as serialized JSON objects, plain JS objects, or entry arrays such as `[['VerifyAuthToken', 'seeded']]`.
The default navigator surface is Chrome-like, including `navigator.userAgent`, `navigator.vendor`, and `navigator.userAgentData`.

## Optional native build

```bash
npm run build:native
```

Local `npm pack` and `npm publish` still build the native addon for the current platform via `prepack`.
Tagged GitHub releases assemble multi-platform prebuilds and publish a single npm package that includes:

- `linux-x64-gnu`
- `win32-x64-msvc`
- `darwin-x64`
- `darwin-arm64`

At runtime the loader picks the matching binary from `prebuilds/<platform>/rom_node_native.node`.

## Common methods

- `eval(script)`
- `evalAsync(script)`
- `evalJson(script, { async })`
- `goto(url, options)`
- `setContent(html, options)`
- `content()`
- `evaluate(pageFunctionOrExpression, arg)`
- `waitForSelector(selector, options)`
- `waitForFunction(pageFunctionOrExpression, arg, options)`
- `click(selector, options)`
- `fill(selector, value, options)`
- `textContent(selector, options)`
- `innerHTML(selector, options)`
- `locator(selector)`
- `surfaceSnapshot()`
- `fingerprintProbe()`
- `runFingerprintJsHarness()`
- `fingerprintJsVersion()`

## Environment

- `ROM_NATIVE_NODE_BINDING`: explicit path to a compiled `.node` addon
- `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
- `ROM_PROXY_URL`: convenience env var you can forward into `proxy_url`

## More docs

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