@rxflex/rom 0.0.1

package/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "rom-node-native"
+description = "Native napi-rs bridge for the ROM Node.js bindings"
+version = "0.0.1"
+edition = "2024"
+homepage = "https://github.com/Rxflex/rom"
+license = "MIT"
+repository = "https://github.com/Rxflex/rom"
+
+[lib]
+name = "rom_node_native"
+path = "native/lib.rs"
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = "3"
+napi-derive = "3"
+rom-runtime = { path = "../../crates/rom-runtime" }
+
+[build-dependencies]
+napi-build = "2"
+
+[workspace]

package/README.md

@@ -0,0 +1,74 @@
+# `@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()`
+- `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/",
+  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);
+```
+
+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.
+
+## Optional native build
+
+```bash
+npm run build:native
+```
+
+`npm pack` and `npm publish` now run the native release build automatically via `prepack`, and the produced `rom_node_native.node` is included in the published tarball for the platform that performed the publish.
+
+## Common methods
+
+- `eval(script)`
+- `evalAsync(script)`
+- `evalJson(script, { async })`
+- `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)

package/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    napi_build::setup();
+}

package/native/lib.rs

@@ -0,0 +1,7 @@
+use napi::Result;
+use napi_derive::napi;
+
+#[napi]
+pub fn execute_bridge(request_json: String) -> Result<String> {
+    Ok(rom_runtime::execute_bridge_request_json(&request_json))
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rxflex/rom",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Node.js wrapper for the ROM browser-like runtime",
+  "license": "MIT",
+  "author": "Rxflex",
+  "homepage": "https://github.com/Rxflex/rom",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rxflex/rom.git",
+    "directory": "bindings/gom-node"
+  },
+  "bugs": {
+    "url": "https://github.com/Rxflex/rom/issues"
+  },
+  "keywords": [
+    "rom",
+    "runtime",
+    "browser",
+    "web-api",
+    "fingerprint"
+  ],
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "scripts": {
+    "prepack": "node ./scripts/build-native.mjs --release",
+    "build:native": "node ./scripts/build-native.mjs --release",
+    "build:native:debug": "node ./scripts/build-native.mjs",
+    "smoke": "node ./scripts/smoke.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "README.md",
+    "rom_node_native.node",
+    "src",
+    "scripts",
+    "native",
+    "Cargo.toml",
+    "build.rs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/build-native.mjs

@@ -0,0 +1,44 @@
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const profile = process.argv.includes("--release") ? "release" : "debug";
+const targetDir = process.env.CARGO_TARGET_DIR || path.join(packageRoot, "target");
+const artifactDir = path.join(targetDir, profile);
+const outputPath = path.join(packageRoot, "rom_node_native.node");
+
+const cargoArgs = ["build", "--manifest-path", "Cargo.toml"];
+if (profile === "release") {
+  cargoArgs.push("--release");
+}
+
+const build = spawnSync("cargo", cargoArgs, {
+  cwd: packageRoot,
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (build.status !== 0) {
+  process.exit(build.status ?? 1);
+}
+
+const artifactName =
+  process.platform === "win32"
+    ? "rom_node_native.dll"
+    : process.platform === "darwin"
+      ? "librom_node_native.dylib"
+      : "librom_node_native.so";
+const artifactPath = path.join(artifactDir, artifactName);
+
+if (!existsSync(artifactPath)) {
+  console.error(`Native addon artifact not found: ${artifactPath}`);
+  process.exit(1);
+}
+
+mkdirSync(path.dirname(outputPath), { recursive: true });
+copyFileSync(artifactPath, outputPath);
+console.log(`Built ${outputPath}`);

package/scripts/smoke.mjs

@@ -0,0 +1,26 @@
+import { RomRuntime, hasNativeBinding } from "../src/index.js";
+
+async function main() {
+  const runtime = new RomRuntime({ href: "https://example.test/" });
+  const href = await runtime.evalAsync("(async () => location.href)()");
+  const snapshot = await runtime.surfaceSnapshot();
+
+  if (!hasNativeBinding()) {
+    throw new Error("Expected Node native binding to be loaded.");
+  }
+
+  if (href !== "https://example.test/") {
+    throw new Error(`Unexpected href: ${href}`);
+  }
+
+  if (snapshot?.globals?.window !== true) {
+    throw new Error("Surface snapshot did not expose window.");
+  }
+
+  console.log(JSON.stringify({ native: true, href }));
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/index.d.ts

@@ -0,0 +1,25 @@
+export interface RuntimeConfig {
+  href?: string;
+  user_agent?: string;
+  app_name?: string;
+  platform?: string;
+  language?: string;
+  languages?: string[];
+  hardware_concurrency?: number;
+  device_memory?: number;
+  webdriver?: boolean;
+}
+
+export declare class RomRuntime {
+  constructor(config?: RuntimeConfig);
+  eval(script: string): Promise<string>;
+  evalAsync(script: string): Promise<string>;
+  evalJson<T = unknown>(script: string, options?: { async?: boolean }): Promise<T>;
+  surfaceSnapshot(): Promise<unknown>;
+  fingerprintProbe(): Promise<unknown>;
+  runFingerprintJsHarness(): Promise<unknown>;
+  fingerprintJsVersion(): Promise<string>;
+}
+
+export declare function createRuntime(config?: RuntimeConfig): RomRuntime;
+export declare function hasNativeBinding(): boolean;

package/src/index.js

@@ -0,0 +1,129 @@
+import { execFile } from "node:child_process";
+import { loadNativeBridge } from "./native.js";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..", "..", "..");
+const nativeBridge = loadNativeBridge();
+
+function resolveBridgeCommand() {
+  if (process.env.ROM_BRIDGE_BIN) {
+    return {
+      file: process.env.ROM_BRIDGE_BIN,
+      args: [],
+      cwd: process.env.ROM_BRIDGE_CWD || repoRoot,
+    };
+  }
+
+  return {
+    file: "cargo",
+    args: ["run", "--quiet", "-p", "rom-runtime", "--bin", "rom_bridge"],
+    cwd: process.env.ROM_BRIDGE_CWD || repoRoot,
+  };
+}
+
+function parseBridgeResponse(stdout, stderr, error) {
+  const trimmed = stdout.trim();
+
+  if (!trimmed) {
+    throw error ?? new Error(`ROM bridge produced no output.\n${stderr}`);
+  }
+
+  let response;
+  try {
+    response = JSON.parse(trimmed);
+  } catch (parseError) {
+    throw new Error(
+      `ROM bridge returned invalid JSON: ${parseError.message}\n${stdout}\n${stderr}`,
+    );
+  }
+
+  if (error || !response.ok) {
+    throw new Error(response.error || error?.message || "ROM bridge command failed.");
+  }
+
+  return response.result;
+}
+
+function runNativeBridge(command, payload) {
+  if (!nativeBridge || typeof nativeBridge.executeBridge !== "function") {
+    return null;
+  }
+
+  const responseText = nativeBridge.executeBridge(JSON.stringify({ command, ...payload }));
+  return Promise.resolve(parseBridgeResponse(responseText, "", null));
+}
+
+function runCliBridge(command, payload) {
+  const bridge = resolveBridgeCommand();
+
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      bridge.file,
+      bridge.args,
+      {
+        cwd: bridge.cwd,
+        env: process.env,
+        maxBuffer: 10 * 1024 * 1024,
+      },
+      (error, stdout, stderr) => {
+        try {
+          resolve(parseBridgeResponse(stdout, stderr, error));
+        } catch (bridgeError) {
+          reject(bridgeError);
+        }
+      },
+    );
+
+    child.stdin.end(JSON.stringify({ command, ...payload }));
+  });
+}
+
+function runBridge(command, payload) {
+  return runNativeBridge(command, payload) ?? runCliBridge(command, payload);
+}
+
+export class RomRuntime {
+  constructor(config = {}) {
+    this.config = config;
+  }
+
+  eval(script) {
+    return runBridge("eval", { config: this.config, script });
+  }
+
+  evalAsync(script) {
+    return runBridge("eval-async", { config: this.config, script });
+  }
+
+  async evalJson(script, { async = true } = {}) {
+    const result = async ? await this.evalAsync(script) : await this.eval(script);
+    return JSON.parse(result);
+  }
+
+  surfaceSnapshot() {
+    return runBridge("surface-snapshot", { config: this.config });
+  }
+
+  fingerprintProbe() {
+    return runBridge("fingerprint-probe", { config: this.config });
+  }
+
+  runFingerprintJsHarness() {
+    return runBridge("fingerprint-js-harness", { config: this.config });
+  }
+
+  fingerprintJsVersion() {
+    return runBridge("fingerprint-js-version", { config: this.config });
+  }
+}
+
+export function createRuntime(config = {}) {
+  return new RomRuntime(config);
+}
+
+export function hasNativeBinding() {
+  return !!nativeBridge;
+}

package/src/native.js

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+
+function candidatePaths() {
+  const candidates = [];
+
+  if (process.env.ROM_NATIVE_NODE_BINDING) {
+    candidates.push(process.env.ROM_NATIVE_NODE_BINDING);
+  }
+
+  candidates.push(path.join(packageRoot, "rom_node_native.node"));
+  return candidates;
+}
+
+export function loadNativeBridge() {
+  if (process.env.ROM_FORCE_CLI_BRIDGE === "1") {
+    return null;
+  }
+
+  for (const candidate of candidatePaths()) {
+    if (!existsSync(candidate)) {
+      continue;
+    }
+
+    try {
+      return require(candidate);
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}