@mochi.js/core 0.3.0 → 0.8.0

package/src/default-profile.ts

@@ -0,0 +1,110 @@
+/**
+ * Auto-pick the host-OS-matching profile when `LaunchOptions.profile` is
+ * omitted. The function below is the pure decision table the
+ * launcher consults; tests stub `(platform, arch)` and assert the mapping
+ * without spinning a Chromium.
+ *
+ * ## Why
+ *
+ * Task 0271 documents the strategic thesis: spoofing Windows from a Linux
+ * server is the wrong default. Linux is a real-user signal, not a bot
+ * signal. WAFs trained on real traffic do not penalize Linux UAs because
+ * Linux desktops are massively overrepresented in high-LTV segments
+ * (developers, engineers, researchers). The signal was always
+ * `HeadlessChrome`, never Linux.
+ *
+ * Lifting host-OS-matching from "user types `profile: 'linux-chrome-stable'`
+ * by hand" into a default removes the entire class of "user accidentally
+ * spoofed Windows from a Linux DC and looked weird to the WAF" failures —
+ * the same argument that drove `detectLinuxServerEnv` for headless mode in
+ *
+ *
+ * ## Mapping
+ *
+ * The host pairs `(process.platform, process.arch)` we currently support:
+ *
+ *   - `linux/x64`     → `linux-chrome-stable`
+ *   - `darwin/arm64`  → `mac-m4-chrome-stable`
+ *   - `darwin/x64`    → `mac-chrome-stable`
+ *   - `win32/x64`     → `windows-chrome-stable`
+ *
+ * Everything else (linux/arm64, freebsd, alpine-musl detection, win32/arm64,
+ * etc.) returns `null` — the launcher then throws with a precise diagnostic
+ * listing the six explicit profile IDs and a pointer to the
+ * choose-your-profile guide. We never silently fall back to a placeholder.
+ *
+ * ## Caveat — darwin/x64
+ *
+ * The current profile catalog (`packages/profiles/data/`) ships
+ * `mac-chrome-stable` as a darwin/arm64 capture (its `os.arch === "arm64"`
+ * in `profile.json`). The mapping above still routes darwin/x64 to
+ * `mac-chrome-stable`; users on Intel Macs
+ * who want a strict arch match should pass `profile` explicitly until an
+ * `mac-intel-chrome-stable` capture lands.
+ *
+ */
+
+import type { ProfileId } from "./launch";
+
+/**
+ * Pure decision table: given the current host's `(process.platform,
+ * process.arch)` pair, return the profile id that best matches the host
+ * OS axis. Returns `null` for unsupported hosts so the launcher can throw
+ * with a precise diagnostic.
+ *
+ * No I/O, no logging — call sites can introspect the value cheaply (e.g.
+ * `console.log(mochi.defaultProfileForHost())`).
+ */
+export function defaultProfileForHost(): ProfileId | null {
+  return resolveDefaultProfileForHost(process.platform, process.arch);
+}
+
+/**
+ * Internal pure resolver, exposed so the unit tests can drive the table
+ * without stubbing global `process`. Mirrors the precedence-table style of
+ * `resolveHeadlessMode`.
+ *
+ * @internal
+ */
+export function resolveDefaultProfileForHost(
+  platform: NodeJS.Platform,
+  arch: string,
+): ProfileId | null {
+  if (platform === "linux" && arch === "x64") return "linux-chrome-stable";
+  if (platform === "darwin" && arch === "arm64") return "mac-m4-chrome-stable";
+  if (platform === "darwin" && arch === "x64") return "mac-chrome-stable";
+  if (platform === "win32" && arch === "x64") return "windows-chrome-stable";
+  return null;
+}
+
+/**
+ * The six real-device profile IDs that `defaultProfileForHost` can return,
+ * surfaced by the launcher's failure-mode diagnostic. Order matches the
+ * brief verbatim so the user-facing message is stable.
+ *
+ * @internal
+ */
+export const EXPLICIT_PROFILE_IDS = [
+  "mac-m4-chrome-stable",
+  "mac-chrome-stable",
+  "mac-chrome-beta",
+  "windows-chrome-stable",
+  "linux-chrome-stable",
+  "mac-brave-stable",
+] as const satisfies readonly ProfileId[];
+
+/**
+ * Build the precise diagnostic emitted when `profile` is omitted on an
+ * unsupported host. Format pinned — keep stable so docs +
+ * LLM-context blocks stay correct.
+ *
+ * @internal
+ */
+export function unsupportedHostMessage(platform: NodeJS.Platform, arch: string): string {
+  const list = EXPLICIT_PROFILE_IDS.map((id) => `  - ${id}`).join("\n");
+  return (
+    `[mochi] launch: no profile supplied and no host-matching default for ` +
+    `platform=${platform} arch=${arch}. Pick one explicitly:\n${list}\n` +
+    `See https://mochijs.com/docs/guides/choose-your-profile for the decision aid.`
+  );
+}

package/src/geo-consistency.ts

@@ -11,7 +11,6 @@
  * + en-US looks like every Tor user.
  *
  * @see PLAN.md §9 — relational consistency, IP/TZ/Locale axis
- * @see tasks/0262-ip-tz-locale-exit-consistency.md
  */
 
 import type { MatrixV1 } from "@mochi.js/consistency";

package/src/geo-probe.ts

@@ -9,11 +9,13 @@
  * first half of the fix (the second half is {@link reconcileGeoConsistency}
  * in `launch.ts`).
  *
- * The probe issues a single GET through the same `wreq` preset the session
- * would use for user traffic, so the geolocation service sees the **same
- * JA4 / headers** as the actual page — the probe doesn't itself become
- * detectable. The probe respects the `proxy` option; if unset, the probe
- * goes direct (which is fine — the user's exit IP is the host's IP).
+ * Post-0.7 the probe rides Chromium itself — same network stack as
+ * `page.goto`, same TLS / H2 / JA4 by definition. The default `ProbeFetch`
+ * adapter delegates to `globalThis.fetch` so {@link probeExitGeo} can run
+ * in a test runner without requiring a live Session; production callers
+ * inject a `Session.fetch`-backed adapter via `launch.ts`. The probe
+ * respects the `proxy` option as a diagnostic-only field — Chromium picks
+ * up `--proxy-server` from the launch flags directly.
  *
  * ### Endpoint registry (verified working 2026-05-09)
  *
@@ -34,14 +36,12 @@
  * mode (default `privacy-fallback`).
  *
  * **No cross-session caching** — proxy IPs rotate; stale cache is worse
- * than no cache. (`docs/limits.md` — task 0262.)
+ * than no cache. (`docs/limits.md` —)
  *
  * @see PLAN.md §9 (relational consistency — IP/TZ/Locale axis)
- * @see tasks/0262-ip-tz-locale-exit-consistency.md
  */
 
 import type { MatrixV1 } from "@mochi.js/consistency";
-import { fetch as netFetch } from "@mochi.js/net";
 
 /**
  * Normalised geolocation derived from one of the probe endpoints. The
@@ -429,22 +429,30 @@ const DEFAULT_PER_ENDPOINT_TIMEOUT_MS = 2000;
 
 /**
  * Injection seam for the underlying HTTP transport. Production uses
- * `@mochi.js/net`'s `fetch` (so the probe carries the same JA4/headers as
- * user traffic). Tests inject a stub.
+ * `Session.fetch` (so the probe carries the same JA4/headers as user
+ * traffic — it IS the browser). Tests inject a stub.
+ *
+ * The `proxy` field is forwarded for diagnostic purposes only; the
+ * actual proxy egress is wired at the Chromium `--proxy-server` flag.
  *
  * @internal
  */
 export type ProbeFetch = (
   url: string,
-  init: { preset: string; proxy?: string; timeoutMs: number },
+  init: { proxy?: string; timeoutMs: number },
 ) => Promise<Response>;
 
 /** Options for {@link probeExitGeo}. */
 export interface ProbeOptions {
-  /** Optional outbound proxy URL — `user:pass@host:port` form is fine. */
+  /** Optional outbound proxy URL — diagnostic-only post-0.7. */
   readonly proxy?: string;
-  /** The matrix whose `wreqPreset` drives the TLS fingerprint of the probe. */
-  readonly matrix: Pick<MatrixV1, "wreqPreset">;
+  /**
+   * The matrix is retained on the API surface for forward-compat (so any
+   * future per-locale endpoint shuffle can read from it) and to keep
+   * call sites stable across the 0.6 → 0.7 transition. The probe itself
+   * no longer reads any field — Chromium owns the TLS fingerprint.
+   */
+  readonly matrix?: Partial<MatrixV1>;
   /**
    * Override the default 4-attempt cap. Tests use 2 to keep wall-time low;
    * production sticks with 4.
@@ -454,7 +462,9 @@ export interface ProbeOptions {
   readonly perEndpointTimeoutMs?: number;
   /**
    * Inject a custom `fetch` transport (for tests). Defaults to
-   * `@mochi.js/net`'s `fetch` so the probe shares the session's TLS preset.
+   * `globalThis.fetch` (test/standalone use) — production calls override
+   * this with a `Session.fetch`-backed adapter so the probe rides the
+   * same Chromium network stack as user traffic.
    * @internal
    */
   readonly fetch?: ProbeFetch;
@@ -467,27 +477,23 @@ export interface ProbeOptions {
 }
 
 /**
- * Default `ProbeFetch` — issues the request through `@mochi.js/net`'s
- * one-shot `fetch` so the geo service sees the same JA4 as user traffic.
+ * Default `ProbeFetch` — falls back to `globalThis.fetch` so the probe
+ * works standalone in tests without a live Session. Production launch
+ * paths inject a `Session.fetch`-backed adapter so the probe shares
+ * Chromium's network stack (and therefore JA4) with user traffic.
  *
- * The per-call timeout is mapped onto the wreq `timeoutMs` field; we do
- * NOT also wrap with `AbortController` because Bun's `Response` from the
- * FFI path is synchronous and we want the wreq layer to own the timeout
- * (a layered `AbortController` would race with the Rust handle drop).
+ * The per-call timeout is enforced via `AbortController`.
  */
 const defaultFetch: ProbeFetch = (url, init) => {
-  return Promise.resolve(
-    netFetch(url, {
-      preset: init.preset,
-      ...(init.proxy !== undefined ? { proxy: init.proxy } : {}),
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), init.timeoutMs);
+  return globalThis
+    .fetch(url, {
       method: "GET",
       headers: { Accept: "application/json" },
-      timeoutMs: init.timeoutMs,
-      // Connect timeout matches the per-endpoint cap — a stuck SYN is the
-      // dominant failure mode against rate-limited endpoints.
-      connectTimeoutMs: init.timeoutMs,
-    }),
-  );
+      signal: ac.signal,
+    })
+    .finally(() => clearTimeout(timer));
 };
 
 /** Fisher-Yates shuffle — non-deterministic, Math.random-backed. */
@@ -570,7 +576,6 @@ export async function probeExitGeo(opts: ProbeOptions): Promise<ExitGeo | null>
       new Promise<Response>((resolve, reject) => {
         try {
           fetchFn(adapter.url, {
-            preset: opts.matrix.wreqPreset,
             ...(opts.proxy !== undefined ? { proxy: opts.proxy } : {}),
             timeoutMs: perEndpointTimeoutMs,
           }).then(resolve, reject);

package/src/index.ts

@@ -19,6 +19,13 @@ export {
   type SendOptions,
   type Unsubscribe,
 } from "./cdp/router";
+// Auto-pick host-OS-matching profile when `LaunchOptions.profile` is omitted
+//  (— paired with the strategic thesis in task 0271).
+export {
+  defaultProfileForHost,
+  EXPLICIT_PROFILE_IDS,
+  resolveDefaultProfileForHost,
+} from "./default-profile";
 // Error surface.
 export { NotImplementedError } from "./errors";
 // Exit-IP / TZ / locale reconciliation (task 0262, PLAN.md §9).
@@ -40,16 +47,33 @@ export {
   mochi,
   type ProfileId,
   type ProxyConfig,
+  resolveHeadlessMode,
 } from "./launch";
+// Linux-server environment detection. Pure helpers for users who want to
+// introspect what mochi inferred (and override `headlessMode` from there).
+// Task 0258 — `mochi.detectLinuxServerEnv()` calls `probeLinuxServerEnv`.
+export {
+  detectLinuxServerEnv,
+  type LinuxServerEnv,
+  type LinuxServerProbes,
+  probeLinuxServerEnv,
+  snapshotProbes,
+} from "./linux-server";
 export {
+  ALL_BROWSER_PERMISSIONS,
+  type BrowserPermission,
   type Cookie,
+  type DomStorage,
+  type DomStorageOptions,
   type GotoOptions,
+  type GrantAllPermissionsOptions,
   type HumanClickOptions,
   type HumanMoveOptions,
   type HumanScrollOptions,
   type HumanTypeOptions,
   Page,
   type PageInit,
+  type ScreenshotOptions,
   type WaitForOptions,
   type WaitState,
   type WaitUntil,
@@ -58,5 +82,13 @@ export { ElementHandle, type ElementHandleInit } from "./page/element-handle";
 // 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 {
+  COOKIE_JAR_FORMAT_VERSION,
+  type CookieJar,
+  type CookieJarFile,
+  type CookieJarOptions,
+  Session,
+  type SessionInit,
+  type StorageSnapshot,
+} from "./session";
 export { VERSION } from "./version";