@mochi.js/core

The primary entry point for mochi — a zero-footprint, Bun-native browser automation framework.

bun add @mochi.js/core

import { mochi } from "@mochi.js/core";

const session = await mochi.launch({
  profile: "linux-chrome-stable",
  seed: "user-12345",
});

const page = await session.newPage();
await page.goto("https://example.com");
await page.humanClick("a");
await session.close();

Status

v0.7.x. mochi.launch() is fully wired: pipe-mode CDP transport, relational (profile, seed) Matrix, JIT-friendly inject delivered via Fetch.fulfillRequest body splice (with Page.addScriptToEvaluateOnNewDocument({ runImmediately: true, worldName: "" }) as the about:blank / data: fallback), behavioral synth, and a Chromium-native session.fetch (routes through CDP — Network.loadNetworkResource for simple GETs, page.evaluate("fetch") for non-GET — so JA4 is real Chrome by definition).

The full [v0.1.4 → v0.2] surface lands as additive minor bumps. See CHANGELOG.md.

What this package gives you

• mochi.launch(opts) — spawn a Chromium-for-Testing instance with a relationally-locked fingerprint matrix derived from (profile, seed). Options include proxy, headless, binary, timeout, geoConsistency (IP/TZ/locale exit reconciliation), and challenges (Turnstile auto-click).
• Session and Page — the runtime objects you drive.
• page.humanClick / humanType / humanScroll — biomechanically-shaped input synthesis (Bezier + Fitts + Gaussian jitter).
• session.fetch — out-of-band requests routed through Chromium itself via CDP. JA4/JA3/H2 are real Chrome by definition because Chromium is the client; cookies inherit from the page's origin; CORS applies for non-GET cross-origin calls.
• page.screenshot(opts?) — PNG / JPEG / WebP via CDP Page.captureScreenshot. Options: format, quality, fullPage, clip, omitBackground, encoding. Element-bounded capture ({ element: handle }) is deferred — see https://mochijs.com/docs/reference/limits.
• session.cookies.{save,load}(path, { pattern? }) — JSON cookie jar with version header + regex domain filter. Round-trips losslessly via Storage.getCookies / Storage.setCookies.
• page.localStorage.{get,set} and page.sessionStorage.{get,set} — direct DOMStorage CDP access, frame-scoped (defaults to current main-frame origin; pass { origin } for cross-origin).
• page.grantAllPermissions(opts?) — wraps Browser.grantPermissions with the full ALL_BROWSER_PERMISSIONS descriptor list.

All of this is the single import. No mixing Patchright + a fingerprint injector + a Turnstile clicker. mochi solves it once.

Why @mochi.js/core?

• Bun-only. No Node fallback. Engines: bun >= 1.1.
• Stock Chromium. No patched fork. Works against Chromium-for-Testing, pinned and downloadable via mochi browsers install.
• Relational locking. Every fingerprint surface (canvas, WebGL, audio, fonts, timing) derives from a single (profile, seed) pair. No Frankenstein fingerprints. Audio + canvas digests are byte-exact via precomputed per-(profile, sample-rate) blobs (R-047 / R-048).
• Zero-jitter spoofing. TurboFan-friendly proxies installed before any page script. Init-script delivery via Fetch.fulfillRequest body splice closes the source-attribution leak that bare addScriptToEvaluateOnNewDocument would otherwise carry.

License

MIT.

See also

• Repo
• PLAN.md — the full design contract

Documentation

• Package reference: https://mochijs.com/docs/api/core
• Concept deep-dive: https://mochijs.com/docs/concepts/stealth-philosophy
• Cookbook: https://mochijs.com/docs/guides/pick-a-scenario