@mochi.js/core 0.0.1

package/README.md

@@ -0,0 +1,53 @@
+# @mochi.js/core
+
+> The primary entry point for **mochi** — a zero-footprint, Bun-native browser automation framework.
+
+```sh
+bun add @mochi.js/core
+```
+
+```ts
+import { mochi } from "@mochi.js/core";
+
+const session = await mochi.launch({
+  profile: "mac-m2-chrome-stable",
+  seed: "user-12345",
+});
+
+const page = await session.newPage();
+await page.goto("https://example.com");
+await page.humanClick("#submit");
+await session.close();
+```
+
+## Status
+
+**v0.0.1 — claim release.** The surface above is the contract; the implementation lands incrementally per the project roadmap. Calling `mochi.launch()` at v0.0.1 throws `NotImplementedError` with a pointer to the repo.
+
+The full surface lands in phases 0.1 → 1.0. Watch the repo for v0.1 (CDP transport) and v1.0 (the production release).
+
+## What this package gives you
+
+- `mochi.launch(opts)` — spawn a Chromium-for-Testing instance with a relationally-locked fingerprint matrix derived from `(profile, seed)`.
+- `Session` and `Page` — the runtime objects you drive.
+- `page.humanClick / humanType / humanScroll` — biomechanically-shaped input synthesis.
+- `session.fetch` — out-of-band requests with profile-matching JA3/JA4 via the Rust+wreq backend.
+
+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](https://googlechromelabs.github.io/chrome-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.
+- **Zero-jitter spoofing.** TurboFan-friendly proxies installed via `Page.addScriptToEvaluateOnNewDocument(runImmediately:true)` before any page script. No async round-trips when a WAF probes.
+
+## License
+
+MIT.
+
+## See also
+
+- [Repo](https://github.com/0xchasercat/mochi.js)
+- [PLAN.md](https://github.com/0xchasercat/mochi.js/blob/main/PLAN.md) — the full design contract
+- [Limits](https://github.com/0xchasercat/mochi.js/blob/main/docs/limits.md) — what the JS-only ceiling honestly does and doesn't cover

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mochi.js/core",
+  "version": "0.0.1",
+  "description": "Bun-native browser automation framework — relational fingerprint locking, zero-jitter injection, behavioral playback. The primary entry point.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "homepage": "https://github.com/0xchasercat/mochi.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xchasercat/mochi.js.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/0xchasercat/mochi.js/issues"
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "chromium",
+    "cdp",
+    "bun",
+    "stealth",
+    "fingerprint",
+    "anti-bot",
+    "playwright-alternative",
+    "puppeteer-alternative"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src/",
+    "lint": "biome check src/",
+    "build": "echo 'no build step yet — Bun consumes src/ directly'"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/smoke.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "bun:test";
+import { mochi, NotImplementedError, VERSION } from "../index";
+
+describe("@mochi.js/core (claim release)", () => {
+  it("exports a VERSION string", () => {
+    expect(typeof VERSION).toBe("string");
+    expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  it("exports a mochi namespace with launch", () => {
+    expect(typeof mochi).toBe("object");
+    expect(typeof mochi.launch).toBe("function");
+    expect(mochi.version).toBe(VERSION);
+  });
+
+  it("mochi.launch throws NotImplementedError until phase 0.1", () => {
+    expect(() => mochi.launch()).toThrow(NotImplementedError);
+    expect(() => mochi.launch()).toThrow(/not yet implemented/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @mochi.js/core — the Bun-native browser automation framework.
+ *
+ * This is a v0.0.1 claim release. The full surface — `mochi.launch()`, `Session`,
+ * `Page`, `humanClick`, `humanType`, `humanScroll` — lands incrementally per
+ * the implementation phases in PLAN.md (phase 0.1 → 1.0).
+ *
+ * @see https://github.com/0xchasercat/mochi.js
+ */
+
+export const VERSION = "0.0.1" as const;
+
+export class NotImplementedError extends Error {
+  constructor(public readonly api: string) {
+    super(
+      `${api} is not yet implemented. mochi is at v${VERSION} (claim release). ` +
+        `See https://github.com/0xchasercat/mochi.js for the implementation roadmap.`,
+    );
+    this.name = "NotImplementedError";
+  }
+}
+
+/**
+ * The mochi namespace. v0.0.1 placeholder; real surface lands in phase 0.1.
+ */
+export const mochi = {
+  /** Framework version. */
+  version: VERSION,
+
+  /**
+   * Launch a browser session. Lands in phase 0.1.
+   *
+   * @example
+   * ```ts
+   * import { mochi } from "@mochi.js/core";
+   * const session = await mochi.launch({ profile: "mac-m2-chrome-stable", seed: "user-1" });
+   * ```
+   */
+  launch(_opts?: unknown): never {
+    throw new NotImplementedError("mochi.launch");
+  },
+} as const;
+
+export type Mochi = typeof mochi;