camoufox 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00e2999e211a2e3ee480426bf3c9eed1a8c0b8760ece361bc2f1fde28db92cad
+  data.tar.gz: b10e48835271556ee652882db960a95087d3a896b2c6fe009b434c0ceb820acf
+SHA512:
+  metadata.gz: d32e355e981ed307fcd1793cab79952cb3512708d1cbeb868e1db90cf60d21e847611b4ade10c9c440f2aee2640ac56af67ea95c25420ef1768dddfe32b266bb
+  data.tar.gz: 939da8ab954c0df051fb00c678a2147ada31fc16447f23a69dc75943a79a50a638d919bf4c85e9f9d1e9f824008d956fd39410ba0b2d43f9d5a5a7826a2baa17

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.2.0
+- Fix native launch options so the provided `headless` flag is respected by Playwright.
+
+## 0.1.0
+- Initial Ruby bridge around the Camoufox Python package (legacy).
+- Native rewrite in progress: mirror `pythonlib/camoufox` structure, remove the Ruby Playwright
+  client dependency, provide stubbed launch options via C++, add an experimental server launcher, and
+  reintroduce a `SyncAPI` helper that drives Playwright through a Node bridge.

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Camoufox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# Camoufox Ruby
+
+Camoufox Ruby is a work-in-progress native port of the
+[Camoufox](https://github.com/daijro/camoufox) toolkit. The project is undergoing a full rewrite to
+mirror the package layout of the reference Python implementation (`pythonlib/camoufox`) while keeping
+all logic inside the Ruby gem.
+
+> **Status:** Everything is stubbed. The gem exposes the same module/file structure as the Python
+> package, but most methods simply return placeholder data or emit warnings. Real fingerprint
+> generation, binary management, networking, and Web API spoofing are still to come.
+
+## Installation
+
+Add the gem directly from the repository while the native rewrite is underway:
+
+```ruby
+gem "camoufox"
+```
+
+### Prerequisites
+
+- Ruby ≥ 3.0 (development targets 3.4.2)
+- Node.js and `npm` (required by Playwright)
+
+### Install steps
+
+```bash
+git clone https://github.com/GaetanJuvin/camoufox-ruby.git
+cd camoufox-ruby
+bundle install
+rake compile
+npx install playwright
+npx playwright install firefox
+```
+
+## Quick start
+
+```ruby
+require "camoufox"
+
+driver_dir = ENV.fetch("CAMOUFOX_PLAYWRIGHT_DRIVER_DIR", File.expand_path("node_modules/playwright", __dir__))
+
+Camoufox.configure do |config|
+  config.playwright_driver_dir = driver_dir
+  config.node_path = ENV["CAMOUFOX_NODE_PATH"] if ENV["CAMOUFOX_NODE_PATH"]
+end
+
+Camoufox::SyncAPI::Camoufox.open(headless: true) do |browser|
+  page = browser.new_page
+  page.goto("https://example.com")
+  puts page.title
+end
+```
+
+Behind the scenes the Ruby port encodes the Camoufox launch options, hands them to a small Node.js
+bridge, and lets Playwright do the heavy lifting. You must supply a Playwright driver bundle or
+installation so the Node script can `require('playwright')`.
+
+### Launching the Playwright server (experimental)
+
+To mirror the Python helper that spins up a Playwright websocket endpoint, the Ruby port can invoke
+Playwright's Node driver directly (no `playwright-ruby-client` dependency). You must provide the
+location of a Playwright driver bundle that contains `lib/browserServerImpl.js`.
+
+```bash
+export CAMOUFOX_PLAYWRIGHT_DRIVER_DIR=/path/to/playwright/driver/package
+export CAMOUFOX_NODE_PATH=/path/to/node   # optional, defaults to `node`
+bundle exec ruby run.rb server
+```
+
+The command prints the websocket endpoint and keeps the process alive, matching the Python
+behaviour. Until the native mapper is complete, the underlying launch options remain stubbed.
+
+## Module layout
+
+The Ruby sources now mirror the structure of `pythonlib/camoufox`:
+
+```
+lib/camoufox/
+├── __init__ (lib/camoufox.rb)
+├── __main__.rb
+├── __version__.rb
+├── addons.rb
+├── async_api.rb
+├── browserforge.yml
+├── exceptions.rb
+├── fingerprints.rb
+├── fonts.json
+├── ip.rb
+├── locale.rb
+├── pkgman.rb
+├── server.rb
+├── sync_api.rb
+├── utils.rb
+├── virtdisplay.rb
+├── warnings.rb
+└── webgl/
+```
+
+Each file defines the corresponding Ruby module, currently implemented as lightweight stubs so that
+call sites can be wired up without crashing.
+
+## CLI
+
+The `bin/camoufox` executable is available, but commands only return informative placeholder
+messages until the native implementation lands.
+
+```bash
+camoufox version  # => "Camoufox native stub v0.0.1"
+```
+
+The repository also includes a helper script, `run.rb`, with convenience commands:
+
+```bash
+bundle exec ruby run.rb                     # show stub details and launch options
+bundle exec ruby run.rb launch-options --locale en-US --headful
+bundle exec ruby run.rb browse --url https://example.com
+bundle exec ruby run.rb server
+
+# or run the sample script directly
+bundle exec ruby examples/sync_playwright.rb
+```
+
+## Configuration
+
+`Camoufox.configure` exposes a tiny configuration object that is growing alongside the native port.
+Today it supports the basic directories and the Playwright driver configuration:
+
+```ruby
+Camoufox.configure do |config|
+  config.data_dir = "/tmp/camoufox-data"
+  config.node_path = "/usr/local/bin/node"
+  config.playwright_driver_dir = "/opt/playwright-driver/package"
+end
+```
+
+Environment overrides:
+
+- `CAMOUFOX_DATA_DIR` – override where Camoufox assets are stored (planned use)
+- `CAMOUFOX_CACHE_DIR` – override the cache directory (planned use)
+- `CAMOUFOX_NODE_PATH` – path to the Node.js binary used when spawning the Playwright server (defaults to `node`)
+- `CAMOUFOX_PLAYWRIGHT_DRIVER_DIR` – directory containing `lib/browserServerImpl.js` (defaults to `node_modules/playwright` if present)
+- `CAMOUFOX_PLAYWRIGHT_JS_REQUIRE` – optional module identifier passed to Node's `require()` when
+  running the synchronous Playwright bridge (defaults to `playwright`)
+
+## Testing
+
+Specs intentionally exercise only the pieces that exist today. Run them after compiling the native
+extension:
+
+```bash
+~/.rbenv/versions/3.4.2/bin/ruby -S bundle exec rspec
+```
+
+## Contributing
+
+See `docs/native_port.md` for the roadmap toward feature parity with the Python Camoufox package.
+
+## License
+
+MIT – see `LICENSE` for details.

data/bin/camoufox

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/camoufox"
+
+if ARGV.empty?
+  warn "Usage: camoufox <command> [args]"
+  exit 1
+end
+
+command = ARGV.shift
+
+begin
+  output = Camoufox::CLI.run(command, ARGV)
+  print(output) unless output.nil? || output.empty?
+rescue Camoufox::MissingNativeExtension => e
+  warn e.message
+  exit 127
+end

data/docs/native_port.md

@@ -0,0 +1,96 @@
+# Camoufox Native Port Plan
+
+This document tracks the work needed to replace the Python bridge with a native C++ implementation
+that exposes the same surface area to the Ruby gem. The goal is to eventually match the behaviour of
+the original Python package (`camoufox`) without shelling out to Python.
+
+## Target surface area
+
+The Ruby gem currently relies on the Python package for the following capabilities:
+
+1. **Launch options** – `camoufox.launch_options` assembles the configuration blob passed to the
+   Camoufox Firefox binary. This touches nearly every helper in `pythonlib/camoufox/utils.py`.
+2. **Binary management** – `camoufox fetch/remove/path/version` download the Firefox bundle from
+   GitHub releases, manage add-ons, fonts, and GeoIP data (`pkgman.py`, `addons.py`, `locale.py`).
+3. **Warnings & validation** – type checking, config validation, leak warnings, logging.
+4. **Virtual display and Playwright helpers** – optional Xvfb integration (Linux), environment
+   variable setup for the executable, proxy/geolocation interactions.
+
+## Major components to port
+
+| Python module | Responsibility | Native port considerations |
+| ------------- | -------------- | --------------------------- |
+| `utils.py` | Fingerprint generation, fonts, WebGL spoofing, config assembly, env var packing | Requires BrowserForge fingerprints DB, WebGL dataset, numpy-like utilities, UA parsing |
+| `fingerprints.py` | Integrates BrowserForge logic | Need a native fingerprint generator and data loader |
+| `pkgman.py` | Download/validate Camoufox binaries from GitHub, version constraints | Re-implement HTTP client, ZIP handling, progress reporting |
+| `addons.py` | Default addon management, path validation | Port addon discovery + download logic |
+| `locale.py` | GeoIP integration, locale selection | Needs MMDB parsing or a replacement library |
+| `webgl/` | Pre-generated WebGL fingerprints | Convert dataset to native-friendly format |
+| `virtdisplay.py` | Manages Xvfb | Detect platform, spawn background process |
+| `cli` commands | fetch/remove/test/version | Recreate CLI front-end in Ruby or C++ |
+
+## Architectural direction
+
+1. **C++ shared library (`libcamoufox_native`)**
+   - Exposes a minimal API surface to Ruby (initially stubbed, later feature-complete).
+   - Organised into modules mirroring the Python package (fingerprint, config, pkgman, addons, geo).
+   - Uses modern C++ (C++20) with libraries for HTTP (e.g., libcurl), JSON (nlohmann/json), YAML
+     (yaml-cpp), ZIP handling (libzip/minizip), and MMDB (libmaxminddb).
+
+2. **Ruby extension**
+   - Built via `extconf.rb` / `mkmf` (or CMake + rake) compiling against the shared library.
+   - Provides Ruby-friendly wrappers around the C++ API (converts to/from `VALUE`).
+
+3. **Data assets**
+   - Ship fingerprint/WebGL datasets as JSON/YAML alongside the gem.
+   - Provide tooling to update assets from upstream Camoufox/BrowserForge releases.
+
+4. **CLI integration**
+   - Re-implement the `camoufox` CLI commands purely in Ruby, calling into the native library for
+     heavy work.
+   - Provide an optional Node.js bridge for Playwright interactions while retaining the ability to
+     talk directly to the Playwright driver (no Ruby gem dependency).
+
+## Milestones
+
+1. **Bootstrap**
+   - Scaffold `ext/camoufox_native` with a shared library exposing `launch_options` (stubbed).
+   - Replace `Camoufox::PythonBridge` with `Camoufox::NativeBridge` calling the extension.
+   - Ensure existing specs pass using stubbed data.
+
+2. **Binary manager parity**
+   - Port GitHub release fetching + ZIP extraction.
+   - Implement `fetch/remove/path/version` in C++.
+
+3. **Fingerprint generation**
+   - Port BrowserForge fingerprint logic (initially with static samples, then full generator).
+   - Implement WebGL + fonts spoofing pipeline.
+
+4. **Advanced features**
+   - GeoIP integration, proxy warnings, virtual display support, leak warnings.
+
+5. **Testing & QA**
+   - Build parity test suite comparing native output with Python reference data.
+   - Automate cross-platform builds.
+
+## Immediate next steps
+
+- Define the data model for fingerprints and decide how to ingest BrowserForge datasets natively.
+- Choose third-party libraries (if any) for HTTP, ZIP, MMDB, JSON, and YAML handling; prototype
+  minimal integrations.
+- Design a stable C API surface for the C++ library so Ruby (and potentially other languages) can
+  interact with it without tight coupling to implementation details.
+- Expand the Node bridge to support more Playwright commands (multi-page workflows, screenshotting,
+  etc.) once the native mapper delivers real launch data.
+
+## Open questions
+
+- How closely do we need to match BrowserForge’s fingerprint distribution? Reuse the dataset or
+  re-implement the generation algorithm?
+- Should the native component expose a stable C API (for reuse in other languages) or remain
+  Ruby-specific for now?
+- Packaging strategy for large assets (fonts, WebGL datasets) in a gem-friendly way.
+- Publishing pipeline for https://github.com/GaetanJuvin/camoufox-ruby (tests, builds, release
+  artifacts).
+
+This document will evolve as the native implementation grows. Contributions welcome.

data/ext/camoufox_native/camoufox_native.cpp

@@ -0,0 +1,70 @@
+#include <ruby.h>
+#include <cstring>
+
+namespace {
+
+VALUE build_stub_launch_options(VALUE rb_options) {
+  VALUE result = rb_hash_new();
+
+  VALUE executable_path = rb_str_new_cstr("/usr/local/bin/camoufox");
+  rb_hash_aset(result, ID2SYM(rb_intern("executable_path")), executable_path);
+
+  VALUE args = rb_ary_new();
+  rb_hash_aset(result, ID2SYM(rb_intern("args")), args);
+
+  VALUE env = rb_hash_new();
+  rb_hash_aset(env, rb_str_new_cstr("CAMOU_CONFIG_1"), rb_str_new_cstr("{}"));
+  rb_hash_aset(result, ID2SYM(rb_intern("env")), env);
+
+  ID headless_id = rb_intern("headless");
+  VALUE headless_key = ID2SYM(headless_id);
+  VALUE headless_value = rb_hash_lookup(rb_options, headless_key);
+
+  if (NIL_P(headless_value)) {
+    headless_value = Qfalse;
+  } else {
+    headless_value = RTEST(headless_value) ? Qtrue : Qfalse;
+  }
+
+  rb_hash_aset(result, headless_key, headless_value);
+
+  return result;
+}
+
+VALUE build_cli_response(const char* command) {
+  if (strcmp(command, "path") == 0) {
+    return rb_str_new_cstr("/usr/local/share/camoufox\n");
+  }
+  if (strcmp(command, "version") == 0) {
+    return rb_str_new_cstr("Camoufox native stub v0.0.1\n");
+  }
+  if (strcmp(command, "fetch") == 0) {
+    return rb_str_new_cstr("Fetch command is not yet implemented in the native port.\n");
+  }
+  if (strcmp(command, "remove") == 0) {
+    return rb_str_new_cstr("Remove command is not yet implemented in the native port.\n");
+  }
+  return rb_str_new_cstr("Unknown command.\n");
+}
+
+VALUE native_launch_options(VALUE self, VALUE rb_options) {
+  return build_stub_launch_options(rb_options);
+}
+
+VALUE native_cli(int argc, VALUE* argv, VALUE self) {
+  if (argc < 1) {
+    rb_raise(rb_eArgError, "command required");
+  }
+  VALUE command_val = argv[0];
+  Check_Type(command_val, T_STRING);
+  const char* command = StringValueCStr(command_val);
+  return build_cli_response(command);
+}
+
+} // namespace
+
+extern "C" void Init_camoufox_native() {
+  VALUE camoufox_module = rb_define_module("CamoufoxNative");
+  rb_define_module_function(camoufox_module, "launch_options", RUBY_METHOD_FUNC(native_launch_options), 1);
+  rb_define_module_function(camoufox_module, "run_cli", RUBY_METHOD_FUNC(native_cli), -1);
+}

data/ext/camoufox_native/extconf.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+extension_name = "camoufox_native"
+
+# Enable C++ compilation
+$CXXFLAGS << " -std=c++20 -Wall -Wextra"
+$CFLAGS << " -std=c99"
+$LDFLAGS << " "
+
+create_makefile(extension_name)

data/lib/camoufox/__main__.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module CLI
+    module_function
+
+    def run(command, args = [], env: {})
+      warn("[camoufox] Native CLI does not yet honour environment overrides") if env && !env.empty?
+      NativeBridge.run_cli(command, args)
+    end
+  end
+end

data/lib/camoufox/__version__.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Camoufox
+  VERSION = "0.2.0"
+end

data/lib/camoufox/addons.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module Addons
+    DefaultAddons = [].freeze
+
+    module_function
+
+    def default_addons
+      DefaultAddons
+    end
+
+    def maybe_download_addons(_addons)
+      warn("[camoufox] addon management is not yet implemented in the native port")
+    end
+
+    def confirm_paths(_addons)
+      true
+    end
+  end
+end

data/lib/camoufox/async_api.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module AsyncAPI
+    module_function
+
+    def new_browser(**launch_kwargs)
+      Utils.launch_options(**launch_kwargs)
+    end
+  end
+end

data/lib/camoufox/browserforge.yml

@@ -0,0 +1 @@
+# Placeholder browserforge dataset for native Camoufox port.

data/lib/camoufox/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Camoufox
+  class Configuration
+    attr_accessor :data_dir, :cache_dir, :node_path, :playwright_driver_dir
+
+    def initialize
+      reset_defaults
+    end
+
+    def reset_defaults
+      @data_dir = ENV['CAMOUFOX_DATA_DIR']
+      @cache_dir = ENV['CAMOUFOX_CACHE_DIR']
+      @node_path = ENV['CAMOUFOX_NODE_PATH'] || 'node'
+      @playwright_driver_dir = ENV['CAMOUFOX_PLAYWRIGHT_DRIVER_DIR']
+    end
+  end
+end

data/lib/camoufox/exceptions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Camoufox
+  class Error < StandardError; end
+
+  class MissingNativeExtension < Error; end
+
+  class MissingPlaywrightDriver < Error; end
+
+  class NodeExecutionFailed < Error
+    attr_reader :status
+
+    def initialize(message, status)
+      super(message)
+      @status = status
+    end
+  end
+end

data/lib/camoufox/fingerprints.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module Fingerprints
+    module_function
+
+    def generate(_options = {})
+      warn("[camoufox] fingerprint generation is not yet implemented in the native port")
+      {}
+    end
+
+    def from_browserforge(_fingerprint, _ff_version)
+      warn("[camoufox] BrowserForge integration is not yet implemented")
+      {}
+    end
+  end
+end

data/lib/camoufox/fonts.json

@@ -0,0 +1,3 @@
+{
+  "stub": []
+}

data/lib/camoufox/ip.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module IP
+    module_function
+
+    def public_ip(_proxy = nil)
+      warn("[camoufox] public IP resolution is not yet implemented")
+      "0.0.0.0"
+    end
+
+    def valid_ipv4(_value)
+      false
+    end
+
+    def valid_ipv6(_value)
+      false
+    end
+  end
+end

data/lib/camoufox/launchServer.js

@@ -0,0 +1,65 @@
+// Adapted from the Camoufox Python implementation
+// Launches the Playwright browser server by invoking the undocumented launchServer API.
+
+const path = require('path');
+const fs = require('fs');
+
+function resolveBrowserServerImpl() {
+  const cwd = process.cwd();
+  const candidate = path.join(cwd, 'lib', 'browserServerImpl.js');
+  try {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    return require(candidate);
+  } catch (error) {
+    console.error('Unable to load Playwright browserServerImpl.js from', candidate);
+    console.error('Set CAMOUFOX_PLAYWRIGHT_DRIVER_DIR to the Playwright driver directory.');
+    process.exit(1);
+  }
+}
+
+const { BrowserServerLauncherImpl } = resolveBrowserServerImpl();
+
+function collectData() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+
+    process.stdin.on('end', () => {
+      const buffer = Buffer.from(data, 'base64');
+      resolve(JSON.parse(buffer.toString()));
+    });
+  });
+}
+
+collectData()
+  .then((options) => {
+    if (options.executablePath && !fs.existsSync(options.executablePath)) {
+      console.warn(`camoufox: executable ${options.executablePath} not found, falling back to Playwright default`);
+      delete options.executablePath;
+    }
+
+    console.time('Server launched');
+    console.info('Launching server...');
+
+    const server = new BrowserServerLauncherImpl('firefox');
+
+    server
+      .launchServer(options)
+      .then((browserServer) => {
+        console.timeEnd('Server launched');
+        console.log('Websocket endpoint:\x1b[93m', browserServer.wsEndpoint(), '\x1b[0m');
+        process.stdin.resume();
+      })
+      .catch((error) => {
+        console.error('Error launching server:', error.message);
+        process.exit(1);
+      });
+  })
+  .catch((error) => {
+    console.error('Error collecting data:', error.message);
+    process.exit(1);
+  });

data/lib/camoufox/locale.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module Locale
+    module_function
+
+    def handle_locales(_locales, config)
+      config
+    end
+
+    def geoip_allowed?
+      false
+    end
+
+    def download_mmdb
+      warn("[camoufox] GeoIP database download is not yet implemented")
+    end
+
+    def remove_mmdb
+      warn("[camoufox] GeoIP cleanup is not yet implemented")
+    end
+  end
+end

data/lib/camoufox/native_bridge.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module NativeBridge
+    module_function
+
+    def ensure_loaded!
+      return if defined?(@loaded) && @loaded
+
+      require 'camoufox_native'
+      @loaded = true
+    rescue LoadError => e
+      raise MissingNativeExtension, "camoufox_native extension is not available: #{e.message}"
+    end
+
+    def launch_options(**kwargs)
+      ensure_loaded!
+      CamoufoxNative.launch_options(kwargs)
+    end
+
+    def run_cli(command, args = [])
+      ensure_loaded!
+      CamoufoxNative.run_cli(command.to_s)
+    end
+
+    def available?
+      ensure_loaded!
+      true
+    rescue MissingNativeExtension
+      false
+    end
+  end
+
+end

data/lib/camoufox/pkgman.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module Pkgman
+    InstallInfo = Struct.new(:path, :version, keyword_init: true)
+
+    module_function
+
+    def fetch_latest
+      warn("[camoufox] binary fetch is not yet implemented in the native port")
+      InstallInfo.new(path: "/usr/local/share/camoufox", version: "0.0.0")
+    end
+
+    def install
+      fetch_latest
+    end
+
+    def remove
+      warn("[camoufox] binary removal is not yet implemented")
+      false
+    end
+
+    def install_dir
+      "/usr/local/share/camoufox"
+    end
+
+    def version_string
+      "0.0.0"
+    end
+  end
+end

data/lib/camoufox/server.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+require "base64"
+require "open3"
+
+module Camoufox
+  module Server
+    module_function
+
+    def launch(**kwargs)
+      launch_config = Utils.launch_options(**kwargs).to_h
+      payload = Base64.strict_encode64(JSON.generate(Utils.camelize_hash(launch_config)))
+
+      driver_dir = Camoufox.configuration.playwright_driver_dir
+      raise MissingPlaywrightDriver, missing_driver_message unless driver_dir && Dir.exist?(driver_dir)
+
+      node_path = Camoufox.configuration.node_path || 'node'
+      script_path = File.expand_path("launchServer.js", __dir__)
+
+      run_node_script(node_path, script_path, driver_dir, payload)
+    end
+
+    def missing_driver_message
+      'Set CAMOUFOX_PLAYWRIGHT_DRIVER_DIR to the Playwright driver directory (contains lib/browserServerImpl.js)'
+    end
+
+    def run_node_script(node_path, script_path, working_dir, payload)
+      env = { 'CAMOUFOX_PLAYWRIGHT_DRIVER_DIR' => working_dir }
+      Open3.popen2e(env, node_path, script_path, chdir: working_dir) do |stdin, stdout_err, wait_thr|
+        stdin.write(payload)
+        stdin.close
+
+        stdout_err.each { |line| puts line }
+
+        status = wait_thr.value
+        return if status.success?
+
+        raise NodeExecutionFailed.new("Playwright server exited with status #{status.exitstatus}", status)
+      end
+    rescue Errno::ENOENT => e
+      raise NodeExecutionFailed.new("Failed to execute #{node_path}: #{e.message}", nil)
+    end
+  end
+end

data/lib/camoufox/sync_api.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "base64"
+require "open3"
+
+module Camoufox
+  module SyncAPI
+    class Camoufox
+      def self.open(**kwargs)
+        browser = new(**kwargs)
+        return browser unless block_given?
+
+        begin
+          yield browser
+        ensure
+          browser.close
+        end
+      end
+
+      def initialize(**kwargs)
+        @launch_options = Utils.launch_options(**kwargs).to_h
+      end
+
+      def new_page
+        Page.new(@launch_options)
+      end
+
+      def close
+        # Nothing to cleanup yet – placeholder for future native resources.
+        nil
+      end
+    end
+
+    class Page
+      attr_reader :title, :content
+
+      def initialize(launch_options)
+        @launch_options = launch_options
+        @title = nil
+        @content = nil
+      end
+
+      def goto(url)
+        result = NodeRunner.visit(@launch_options, url)
+        @title = result['title']
+        @content = result['content']&.to_s
+        self
+      end
+    end
+
+    module NodeRunner
+      module_function
+
+      def visit(launch_options, url)
+        node_path = ::Camoufox.configuration.node_path || 'node'
+        script_path = File.expand_path('visit.js', __dir__)
+
+        payload = Base64.strict_encode64(
+          JSON.generate(
+            options: Utils.camelize_hash(launch_options),
+            url: url,
+          ),
+        )
+
+        env = {}
+        if (driver_dir = ::Camoufox.configuration.playwright_driver_dir)
+          env['NODE_PATH'] = [driver_dir, ENV['NODE_PATH']].compact.join(File::PATH_SEPARATOR)
+          env['CAMOUFOX_PLAYWRIGHT_DRIVER_DIR'] = driver_dir
+        end
+
+        stdout, stderr, status = Open3.capture3(env, node_path, script_path, stdin_data: payload)
+
+        unless status.success?
+          message = stderr.empty? ? stdout : stderr
+          raise NodeExecutionFailed.new("Playwright visit failed: #{message.strip}", status)
+        end
+
+        JSON.parse(stdout)
+      rescue Errno::ENOENT => e
+        raise NodeExecutionFailed.new("Failed to execute #{node_path}: #{e.message}", nil)
+      rescue JSON::ParserError => e
+        raise NodeExecutionFailed.new("Invalid response from Playwright visit: #{e.message}", nil)
+      end
+    end
+  end
+end

data/lib/camoufox/utils.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module Utils
+    module_function
+
+    def launch_options(**kwargs)
+      LaunchOptions.new(NativeBridge.launch_options(**kwargs))
+    end
+
+    def camel_case(key)
+      segments = key.to_s.split('_')
+      return key.to_s if segments.length < 2
+
+      [segments.first, *segments[1..].map { |segment| segment[0].to_s.upcase + segment[1..].to_s }].join
+    end
+
+    def camelize_hash(hash)
+      camelize(hash)
+    end
+
+    def camelize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), acc|
+          acc[camel_case(k)] = camelize(v)
+        end
+      when Array
+        value.map { |element| camelize(element) }
+      else
+        value
+      end
+    end
+  end
+
+  class LaunchOptions
+    attr_reader :raw
+
+    def initialize(raw_hash)
+      @raw = symbolize_top_level(raw_hash)
+    end
+
+    def to_h
+      raw.dup
+    end
+
+    private
+
+    def symbolize_top_level(hash)
+      hash.each_with_object({}) do |(key, value), acc|
+        sym_key = key.respond_to?(:to_sym) ? key.to_sym : key
+        acc[sym_key] = deep_dup(value)
+      end
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), acc|
+          acc[k] = deep_dup(v)
+        end
+      when Array
+        value.map { |element| deep_dup(element) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/camoufox/virtdisplay.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module Virtdisplay
+    module_function
+
+    def start(_debug: false)
+      warn("[camoufox] virtual display is not yet implemented")
+      nil
+    end
+
+    def stop
+      nil
+    end
+  end
+end

data/lib/camoufox/visit.js

@@ -0,0 +1,77 @@
+const path = require('path');
+const fs = require('fs');
+
+function readStdinAsBase64() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => resolve(chunks.join('')));
+    process.stdin.on('error', (error) => reject(error));
+  });
+}
+
+function loadPlaywright() {
+  const override = process.env.CAMOUFOX_PLAYWRIGHT_JS_REQUIRE;
+  if (override) {
+    return require(override);
+  }
+
+  try {
+    return require('playwright');
+  } catch (error) {
+    // fall through
+  }
+
+  const driverDir = process.env.CAMOUFOX_PLAYWRIGHT_DRIVER_DIR;
+  if (driverDir) {
+    try {
+      return require(path.join(driverDir, 'package'));
+    } catch (error) {
+      // fall through
+    }
+  }
+
+  console.error('Unable to require Playwright. Install the `playwright` npm package or set CAMOUFOX_PLAYWRIGHT_JS_REQUIRE.');
+  process.exit(1);
+}
+
+async function main() {
+  const payloadB64 = await readStdinAsBase64();
+  const payload = JSON.parse(Buffer.from(payloadB64, 'base64').toString());
+  const { options, url } = payload;
+
+  if (options.executablePath && !fs.existsSync(options.executablePath)) {
+    console.warn(`camoufox: executable ${options.executablePath} not found, falling back to Playwright default`);
+    delete options.executablePath;
+  }
+
+  const playwright = loadPlaywright();
+  const browserType = playwright.firefox;
+  if (!browserType) {
+    console.error('Playwright module does not expose `firefox`.');
+    process.exit(1);
+  }
+
+  const browser = await browserType.launch(options);
+  const page = await browser.newPage();
+  await page.goto(url, { waitUntil: 'domcontentloaded' });
+  try {
+    await page.waitForLoadState('networkidle', { timeout: 15000 });
+  } catch (error) {
+    console.warn(`camoufox: waitForLoadState(networkidle) warning: ${error.message || error}`);
+  }
+
+  const [title, content] = await Promise.all([
+    page.title(),
+    page.content(),
+  ]);
+
+  console.log(JSON.stringify({ title, content }));
+  await browser.close();
+}
+
+main().catch((error) => {
+  console.error(error.message || error);
+  process.exit(1);
+});

data/lib/camoufox/warnings.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Camoufox
+  module Warnings
+    module_function
+
+    def warn(feature, message = nil)
+      note = message || "#{feature} is not yet implemented"
+      Kernel.warn("[camoufox] #{note}")
+    end
+  end
+end

data/lib/camoufox/warnings.yml

@@ -0,0 +1 @@
+# Placeholder warnings configuration for the Camoufox native port.

data/lib/camoufox/webgl/README.md

@@ -0,0 +1 @@
+Placeholder WebGL dataset for the Camoufox native port.

data/lib/camoufox.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "camoufox/__version__"
+require_relative "camoufox/exceptions"
+require_relative "camoufox/configuration"
+# Core helpers
+require_relative "camoufox/utils"
+require_relative "camoufox/addons"
+require_relative "camoufox/fingerprints"
+require_relative "camoufox/ip"
+require_relative "camoufox/locale"
+require_relative "camoufox/pkgman"
+require_relative "camoufox/sync_api"
+require_relative "camoufox/async_api"
+require_relative "camoufox/server"
+require_relative "camoufox/virtdisplay"
+require_relative "camoufox/warnings"
+require_relative "camoufox/native_bridge"
+require_relative "camoufox/__main__"
+
+module Camoufox
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def launch_options(**kwargs)
+      Utils.launch_options(**kwargs)
+    end
+
+    def fetch(update_browserforge: false, env: {})
+      CLI.run("fetch", update_browserforge ? ["--browserforge"] : [], env: env)
+    end
+
+    def remove(env: {})
+      CLI.run("remove", [], env: env)
+    end
+
+    def path(env: {})
+      CLI.run("path", [], env: env).strip
+    end
+
+    def version(env: {})
+      CLI.run("version", [], env: env)
+    end
+  end
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: camoufox
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Camoufox contributors
+bindir: bin
+cert_chain: []
+date: 2025-11-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: Reimplements the pythonlib/camoufox package structure in Ruby with a
+  native extension stub while the full feature set is ported over.
+email:
+- opensource@camoufox.dev
+executables:
+- camoufox
+extensions:
+- ext/camoufox_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- bin/camoufox
+- docs/native_port.md
+- ext/camoufox_native/camoufox_native.cpp
+- ext/camoufox_native/extconf.rb
+- lib/camoufox.rb
+- lib/camoufox/__main__.rb
+- lib/camoufox/__version__.rb
+- lib/camoufox/addons.rb
+- lib/camoufox/async_api.rb
+- lib/camoufox/browserforge.yml
+- lib/camoufox/configuration.rb
+- lib/camoufox/exceptions.rb
+- lib/camoufox/fingerprints.rb
+- lib/camoufox/fonts.json
+- lib/camoufox/ip.rb
+- lib/camoufox/launchServer.js
+- lib/camoufox/locale.rb
+- lib/camoufox/native_bridge.rb
+- lib/camoufox/pkgman.rb
+- lib/camoufox/server.rb
+- lib/camoufox/sync_api.rb
+- lib/camoufox/utils.rb
+- lib/camoufox/virtdisplay.rb
+- lib/camoufox/visit.js
+- lib/camoufox/warnings.rb
+- lib/camoufox/warnings.yml
+- lib/camoufox/webgl/README.md
+- lib/camoufox_native.bundle
+homepage: https://github.com/daijro/camoufox
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/daijro/camoufox
+  source_code_uri: https://github.com/daijro/camoufox-ruby
+  changelog_uri: https://github.com/daijro/camoufox-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Native rewrite of the Camoufox stealth Firefox toolkit
+test_files: []