@mochi.js/core 0.0.1 → 0.1.2

package/src/cdp/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Minimal hand-curated CDP type surface. Mochi deliberately does NOT depend on
+ * `chrome-devtools-protocol` — the generated full surface is multi-megabyte and
+ * only a small slice is referenced. We grow this file as needed; every type
+ * here corresponds to a method or event Mochi actually issues.
+ *
+ * Reference: https://chromedevtools.github.io/devtools-protocol/
+ *
+ * @see PLAN.md §8 — CDP engine design notes
+ */
+
+/** A monotonic CDP request id. */
+export type CdpRequestId = number;
+
+/** A logical CDP session (string id assigned by the browser). */
+export type CdpSessionId = string;
+
+/**
+ * The on-the-wire shape of an outbound CDP command. Optional `sessionId` routes
+ * to a sub-target; absent = root browser target.
+ */
+export interface CdpRequest {
+  id: CdpRequestId;
+  method: string;
+  params?: unknown;
+  sessionId?: CdpSessionId;
+}
+
+/** Inbound CDP message — either a response to an `id`, or an event. */
+export interface CdpResponse {
+  id?: CdpRequestId;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+  method?: string;
+  params?: unknown;
+  sessionId?: CdpSessionId;
+}
+
+/**
+ * A successful CDP response payload. The transport returns this when `error` is
+ * absent; the caller is responsible for typing `result` to a method-specific
+ * shape.
+ */
+export type CdpResultEnvelope<T = unknown> = { result: T };
+
+/**
+ * Subset of `Runtime.RemoteObject`. We only care about `objectId` (for
+ * callFunctionOn round-trips) and `value`/`type` for primitive returns.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/tot/Runtime/#type-RemoteObject
+ */
+export interface RemoteObject {
+  type: "object" | "function" | "undefined" | "string" | "number" | "boolean" | "symbol" | "bigint";
+  subtype?: string;
+  className?: string;
+  /** Present when the value is JSON-serializable. */
+  value?: unknown;
+  /** Present when the object lives only by reference; required for callFunctionOn. */
+  objectId?: string;
+  description?: string;
+}
+
+/** Subset of `DOM.Node` we consult. */
+export interface DomNode {
+  nodeId: number;
+  backendNodeId: number;
+  nodeType: number;
+  nodeName: string;
+}
+
+/** Subset of `Page.Frame`. */
+export interface PageFrame {
+  id: string;
+  parentId?: string;
+  url: string;
+  loaderId?: string;
+}
+
+/** `Page.frameAttached` event params. */
+export interface FrameAttachedEvent {
+  frameId: string;
+  parentFrameId?: string;
+}
+
+/** `Page.frameNavigated` event params. */
+export interface FrameNavigatedEvent {
+  frame: PageFrame;
+}
+
+/** `Target.attachedToTarget` event params. */
+export interface AttachedToTargetEvent {
+  sessionId: CdpSessionId;
+  targetInfo: {
+    targetId: string;
+    type: string;
+    title: string;
+    url: string;
+    attached: boolean;
+  };
+  waitingForDebugger: boolean;
+}
+
+/**
+ * Subset of `DOM.BoxModel` we consume in `Page.humanClick`. CDP returns the
+ * border-box (and content-box, padding-box, etc.) as flat 8-number quads:
+ * `[x0, y0, x1, y1, x2, y2, x3, y3]` walking the corners CCW.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/tot/DOM/#type-BoxModel
+ */
+export interface BoxModel {
+  content: readonly number[];
+  border: readonly number[];
+  padding: readonly number[];
+  margin: readonly number[];
+  width: number;
+  height: number;
+}
+
+/**
+ * Subset of `Input.dispatchMouseEvent` parameters we send. The full CDP type
+ * has many optional fields; we only construct the ones the behavioral path
+ * actually needs.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/tot/Input/#method-dispatchMouseEvent
+ */
+export interface DispatchMouseEventParams {
+  type: "mousePressed" | "mouseReleased" | "mouseMoved" | "mouseWheel";
+  x: number;
+  y: number;
+  button?: "none" | "left" | "middle" | "right";
+  buttons?: number;
+  clickCount?: number;
+  modifiers?: number;
+  deltaX?: number;
+  deltaY?: number;
+}
+
+/**
+ * Subset of `Input.dispatchKeyEvent` parameters we send.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/tot/Input/#method-dispatchKeyEvent
+ */
+export interface DispatchKeyEventParams {
+  type: "keyDown" | "keyUp" | "rawKeyDown" | "char";
+  key?: string;
+  code?: string;
+  text?: string;
+  unmodifiedText?: string;
+  modifiers?: number;
+  windowsVirtualKeyCode?: number;
+  nativeVirtualKeyCode?: number;
+}

package/src/errors.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared error types for `@mochi.js/core`. Centralized so internal modules can
+ * import without going through the public index barrel.
+ */
+
+import { VERSION } from "./version";
+
+/**
+ * Thrown when a public API surface is declared by the v1 contract but not yet
+ * implemented in the current phase. Always names the target API so callers can
+ * grep for the milestone in PLAN.md.
+ */
+export class NotImplementedError extends Error {
+  readonly api: string;
+  constructor(api: string) {
+    super(
+      `${api} is not yet implemented. mochi is at v${VERSION}. ` +
+        "See PLAN.md §14 (Implementation phases) for the roadmap.",
+    );
+    this.name = "NotImplementedError";
+    this.api = api;
+  }
+}

package/src/index.ts

@@ -1,44 +1,51 @@
 /**
- * @mochi.js/core — the Bun-native browser automation framework.
+ * `@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).
+ * Phase 0.1: pipe-mode CDP transport + minimal Session/Page lands here. The
+ * spoofing pipeline (consistency + inject) wires in phases 0.2 → 0.3; the
+ * behavioral surface (humanClick/Type/Scroll) lands in phase 0.8. See PLAN.md
+ * §14 for the full roadmap.
  *
- * @see https://github.com/0xchasercat/mochi.js
+ * @see https://github.com/0xchasercat/mochi
  */
 
-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;
+export { ChromiumNotFoundError } from "./binary";
+export { ForbiddenCdpMethodError } from "./cdp/forbidden";
+export {
+  BrowserCrashedError,
+  type CdpEventHandler,
+  CdpRemoteError,
+  CdpTimeoutError,
+  type SendOptions,
+  type Unsubscribe,
+} from "./cdp/router";
+// Error surface.
+export { NotImplementedError } from "./errors";
+// Public surface — exported here so users only need `@mochi.js/core`.
+export {
+  type ChallengeLaunchOptions,
+  type LaunchOptions,
+  launch,
+  type Mochi,
+  mochi,
+  type ProfileId,
+  type ProxyConfig,
+} from "./launch";
+export {
+  type Cookie,
+  type GotoOptions,
+  type HumanClickOptions,
+  type HumanMoveOptions,
+  type HumanScrollOptions,
+  type HumanTypeOptions,
+  Page,
+  type PageInit,
+  type WaitForOptions,
+  type WaitState,
+  type WaitUntil,
+} from "./page";
+// Proxy URL parsing — exported so tests + downstream tools can normalize
+// proxy strings without going through `launch()`.
+export { type ParsedProxy, parseProxyUrl } from "./proxy-auth";
+export { Session, type SessionInit, type StorageSnapshot } from "./session";
+export { VERSION } from "./version";

package/src/launch.ts

@@ -0,0 +1,282 @@
+/**
+ * `mochi.launch()` — entry point for opening a Session.
+ *
+ * v0.2 wires `@mochi.js/consistency`'s `deriveMatrix` into the launch path:
+ * the input `(profile, seed)` flows through the rule DAG and the resolved
+ * `MatrixV1` is stamped on the Session. The Matrix is **not** yet injected
+ * into the page — that's phase 0.3 (`@mochi.js/inject`). The browser still
+ * sees its native fingerprints; only `Session.profile` carries the spoof.
+ *
+ * @see PLAN.md §5.1 / §7 / §14
+ */
+
+import { deriveMatrix, type ProfileV1 } from "@mochi.js/consistency";
+import { resolveBinary } from "./binary";
+import { spawnChromium } from "./proc";
+import { parseProxyUrl } from "./proxy-auth";
+import { Session } from "./session";
+import { VERSION } from "./version";
+
+/** Profile reference accepted by `mochi.launch`. */
+export type ProfileId = string;
+
+/** Proxy spec accepted by `mochi.launch`. */
+export interface ProxyConfig {
+  server: string;
+  username?: string;
+  password?: string;
+}
+
+/**
+ * Per-challenge convenience options surfaced via `LaunchOptions.challenges`.
+ *
+ * v0.2 implements `turnstile.autoClick` only. Other entries (hCaptcha,
+ * reCAPTCHA, etc.) are reserved for v0.3+ — see `@mochi.js/challenges`
+ * README.
+ *
+ * When `turnstile.autoClick: true`, the `Session` calls
+ * `installTurnstileAutoClick(page)` on every page returned by `newPage`.
+ * The handle is disposed automatically on page close.
+ *
+ * The full `TurnstileOptions` (timeout / humanize / onSolved / onEscalation)
+ * are passed through unchanged. See
+ * `@mochi.js/challenges#TurnstileOptions`.
+ */
+export interface ChallengeLaunchOptions {
+  turnstile?: {
+    /** When `true`, auto-install Turnstile detection + click on every newPage. */
+    autoClick?: boolean;
+    /** Override the per-widget post-click timeout (ms). Default 30_000. */
+    timeout?: number;
+    /** When `false`, use a fast non-humanized click path. Default `true`. */
+    humanize?: boolean;
+    /** Fired when a widget reports a token. */
+    onSolved?: (token: string) => void;
+    /** Fired on image-challenge / managed-variant / timeout. */
+    onEscalation?: (reason: "image-challenge" | "managed" | "timeout") => void;
+    /** Override the DOM-poll cadence (ms). Default 500. */
+    pollIntervalMs?: number;
+  };
+}
+
+/**
+ * Options accepted by `mochi.launch`.
+ *
+ * v0.2 behavior of fields:
+ *   - `profile`, `seed`: drive `@mochi.js/consistency.deriveMatrix` to
+ *     produce a relationally-locked `MatrixV1`. The Matrix is exposed via
+ *     `Session.profile` but **not yet injected** into the page (phase 0.3).
+ *   - `binary`: explicit override. Highest-priority resolution path.
+ *   - `headless`: passes `--headless=new` to Chromium.
+ *   - `proxy`: passes `--proxy-server=<server>` to Chromium with credentials
+ *     stripped (Chromium rejects inline auth on that flag). When credentials
+ *     are present (either in the URL form `http://user:pass@host:port` or
+ *     via `ProxyConfig.username`/`password`) the Session installs a CDP
+ *     `Fetch.authRequired` handler so HTTP / HTTPS / SOCKS5 / SOCKS4 proxy
+ *     auth challenges are answered transparently. See
+ *     `packages/core/src/proxy-auth.ts` for the invariant rationale.
+ *   - `args`: appended after the default flag set.
+ *   - `out.traceDir`: not yet honored at v0.1.
+ *   - `timeout`: per-CDP-request default; defaults to 30000ms.
+ *   - `bypassInject`: short-circuits the inject payload entirely (see field
+ *     JSDoc). Intended for `mochi capture` and similar baseline-collection
+ *     flows — never enable in production.
+ */
+export interface LaunchOptions {
+  profile: ProfileId | ProfileV1;
+  seed: string;
+  proxy?: string | ProxyConfig;
+  headless?: boolean;
+  binary?: string;
+  args?: string[];
+  out?: { traceDir?: string };
+  timeout?: number;
+  /**
+   * When `true`, the {@link Session} skips both `buildPayload` (no payload
+   * is compiled) and `Page.addScriptToEvaluateOnNewDocument` on every new
+   * page. Auto-attached worker / service-worker / audio-worklet targets
+   * are likewise NOT injected — the browser reports its bare, un-spoofed
+   * fingerprints.
+   *
+   * Intended for `mochi capture` and similar baseline-collection flows;
+   * **do not enable in production**. The whole point of mochi is the
+   * inject pipeline; bypassing it produces a session that will be
+   * trivially fingerprinted as Chromium-for-Testing.
+   *
+   * Defaults to `false`. PLAN.md §12.1 (capture must run against bare
+   * Chromium); task 0040.
+   */
+  bypassInject?: boolean;
+  /**
+   * Convenience layer toggles for common bot-defense widgets. When
+   * `challenges.turnstile.autoClick` is `true`, every page returned by
+   * `Session.newPage` has `installTurnstileAutoClick(page, opts)` wired
+   * automatically — the Bezier+Fitts behavioral synth handles the click,
+   * an optional `onSolved` callback fires when the response token appears,
+   * and `onEscalation` fires on image-challenge / managed-variant / timeout.
+   *
+   * See `@mochi.js/challenges` for the full surface and the limits page
+   * for the v0.2 scope (visible-checkbox variants only — image/audio
+   * solving is v0.3+).
+   */
+  challenges?: ChallengeLaunchOptions;
+}
+
+/**
+ * Launch a Session: spawn Chromium with `--remote-debugging-pipe`, attach the
+ * CDP transport, and return a configured `Session`.
+ */
+export async function launch(opts: LaunchOptions): Promise<Session> {
+  const binary = await resolveBinary(opts.binary);
+  const normalized = normalizeProxy(opts.proxy);
+  const proc = await spawnChromium({
+    binary,
+    extraArgs: opts.args,
+    headless: opts.headless ?? false,
+    // Chromium rejects inline auth on `--proxy-server`; pass the
+    // auth-stripped server URL.
+    ...(normalized !== undefined ? { proxy: normalized.server } : {}),
+  });
+
+  // Resolve the `MatrixV1` for this session via the consistency engine.
+  // Inline `ProfileV1` objects flow straight through; string profile ids
+  // are resolved against a placeholder profile until `@mochi.js/profiles`
+  // ships its first capture (phase 0.4). The matrix is bit-stable per
+  // `(profile, seed)` excluding the `derivedAt` timestamp.
+  const profile = resolveProfile(opts.profile);
+  const matrix = deriveMatrix(profile, opts.seed);
+
+  const session = new Session({
+    proc,
+    matrix,
+    seed: opts.seed,
+    ...(opts.timeout !== undefined ? { defaultTimeoutMs: opts.timeout } : {}),
+    ...(opts.bypassInject === true ? { bypassInject: true } : {}),
+    // Forward the same proxy (with auth, if any) to the net FFI so
+    // out-of-band Session.fetch traffic shares the apparent egress.
+    // `@mochi.js/net` (wreq) accepts the full `user:pass@host` URL form.
+    ...(normalized !== undefined ? { netProxy: normalized.netProxy } : {}),
+    ...(normalized?.auth !== undefined ? { proxyAuth: normalized.auth } : {}),
+    ...(opts.challenges !== undefined ? { challenges: opts.challenges } : {}),
+  });
+  return session;
+}
+
+/**
+ * The public namespace exposed via `import { mochi } from "@mochi.js/core"`.
+ */
+export const mochi = {
+  /** Framework version. */
+  version: VERSION,
+  /** Launch a browser session. */
+  launch,
+} as const;
+
+export type Mochi = typeof mochi;
+
+// ---- helpers ----------------------------------------------------------------
+
+/**
+ * Reconcile the two `LaunchOptions.proxy` shapes (URL string and
+ * `ProxyConfig` record) into a single normalized record carrying:
+ *   - `server`: auth-stripped URL safe to feed `--proxy-server=`.
+ *   - `netProxy`: the URL handed to the network FFI. Preserves credentials
+ *     (wreq accepts `user:pass@host` inline) so out-of-band fetches
+ *     authenticate against the same proxy.
+ *   - `auth`: parsed credentials for the CDP auth handler. Undefined when
+ *     no creds were supplied.
+ *
+ * Returns `undefined` only when no proxy was configured at all.
+ */
+function normalizeProxy(p: LaunchOptions["proxy"]):
+  | {
+      server: string;
+      netProxy: string;
+      auth?: { username: string; password: string };
+    }
+  | undefined {
+  if (p === undefined) return undefined;
+  if (typeof p === "string") {
+    if (p.length === 0) return undefined;
+    const parsed = parseProxyUrl(p);
+    return {
+      server: parsed.server,
+      netProxy: p,
+      ...(parsed.auth !== undefined ? { auth: parsed.auth } : {}),
+    };
+  }
+  // ProxyConfig form. `server` may itself include credentials; if so we
+  // strip them. Explicit username/password fields take precedence.
+  const parsed = parseProxyUrl(p.server);
+  const auth =
+    p.username !== undefined ? { username: p.username, password: p.password ?? "" } : parsed.auth;
+  // Reconstruct the netProxy URL preserving any explicit auth (wreq path).
+  const netProxy = auth !== undefined ? injectAuth(parsed.server, auth) : parsed.server;
+  return {
+    server: parsed.server,
+    netProxy,
+    ...(auth !== undefined ? { auth } : {}),
+  };
+}
+
+/**
+ * Inject `username:password@` into a server URL, percent-encoding both
+ * components so reserved characters round-trip cleanly through wreq's URL
+ * parser.
+ */
+function injectAuth(server: string, auth: { username: string; password: string }): string {
+  const u = encodeURIComponent(auth.username);
+  const p = encodeURIComponent(auth.password);
+  // server is `<protocol>://<host>:<port>` (per parseProxyUrl).
+  const idx = server.indexOf("://");
+  if (idx < 0) return server;
+  const head = server.slice(0, idx + 3);
+  const tail = server.slice(idx + 3);
+  return `${head}${u}:${p}@${tail}`;
+}
+
+/**
+ * Resolve `LaunchOptions.profile` into a concrete `ProfileV1`. Inline
+ * profiles flow through unchanged. String profile ids — until
+ * `@mochi.js/profiles` ships (phase 0.4) — resolve to a generic placeholder
+ * stamped with the id; the consistency engine still produces a real,
+ * relationally-locked Matrix from it.
+ */
+function resolveProfile(profile: ProfileId | ProfileV1): ProfileV1 {
+  if (typeof profile === "object") return profile;
+  return {
+    id: profile,
+    version: "0.0.0-placeholder",
+    engine: "chromium",
+    browser: { name: "chrome", channel: "stable", minVersion: "131", maxVersion: "133" },
+    os: { name: "linux", version: "22", arch: "x64" },
+    device: {
+      vendor: "generic",
+      model: "generic-x64",
+      cpuFamily: "intel-core-i7",
+      cores: 8,
+      memoryGB: 16,
+    },
+    display: { width: 1920, height: 1080, dpr: 1, colorDepth: 24, pixelDepth: 24 },
+    gpu: {
+      vendor: "Intel Inc.",
+      renderer: "Intel Iris Xe Graphics",
+      webglUnmaskedVendor: "Google Inc. (Intel Inc.)",
+      webglUnmaskedRenderer: "ANGLE (Intel Inc., Intel Iris Xe Graphics, OpenGL 4.1)",
+      webglMaxTextureSize: 16384,
+      webglMaxColorAttachments: 8,
+      webglExtensions: [],
+    },
+    audio: { contextSampleRate: 48000, audioWorkletLatency: 0.005, destinationMaxChannelCount: 2 },
+    fonts: { family: "linux-baseline", list: ["DejaVu Sans"] },
+    timezone: "UTC",
+    locale: "en-US",
+    languages: ["en-US", "en"],
+    behavior: { hand: "right", tremor: 0.18, wpm: 60, scrollStyle: "smooth" },
+    wreqPreset: "chrome_131_linux",
+    userAgent:
+      "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+    uaCh: {},
+    entropyBudget: { fixed: [], perSeed: [] },
+  };
+}