@mochi.js/core 0.6.0 → 0.8.0

package/src/launch.ts

@@ -92,7 +92,7 @@ export interface LaunchOptions {
    * string (looked up against `KNOWN_PROFILE_IDS`) or an inline `ProfileV1`
    * object.
    *
-   * **Optional since task 0272** — when omitted, mochi auto-picks the
+   * **Optional** — when omitted, mochi auto-picks the
    * profile whose declared OS matches the host's `process.platform` /
    * `process.arch` pair via {@link defaultProfileForHost}:
    *
@@ -120,7 +120,7 @@ export interface LaunchOptions {
    * `false` (default in v0.1) runs headful. New code should prefer
    * {@link headlessMode}, which is more expressive AND env-aware.
    *
-   * Resolution priority (task 0258):
+   * Resolution priority:
    *
    *   1. `headlessMode` if set.
    *   2. Else `headless: true → "new"`, `headless: false → "off"`.
@@ -130,7 +130,7 @@ export interface LaunchOptions {
    */
   headless?: boolean;
   /**
-   * Headless dispatch mode (task 0258). One of:
+   * Headless dispatch mode. One of:
    *
    *   - `"new"`    — modern Chromium headless (`--headless=new`). Full
    *                  rendering, near-byte-identical to headful for
@@ -178,7 +178,7 @@ export interface LaunchOptions {
    * trivially fingerprinted as Chromium-for-Testing.
    *
    * Defaults to `false`. PLAN.md §12.1 (capture must run against bare
-   * Chromium); task 0040.
+   * Chromium);
    */
   bypassInject?: boolean;
   /**
@@ -199,7 +199,7 @@ export interface LaunchOptions {
    *
    * Pairs with — but is independent of — {@link bypassInject}. Capture
    * flows set both `true`; harness conformance runs set `hermetic: true`
-   * with full inject pipeline active. PLAN.md §8.6 + task 0256.
+   * with full inject pipeline active. PLAN.md §8.6 +
    */
   hermetic?: boolean;
   /**
@@ -235,13 +235,13 @@ export interface LaunchOptions {
    * - `"off"` — skip the probe entirely. Use in offline tests / when
    *   the probe service is rate-limited.
    *
-   * The probe is a single GET through wreq (using the matrix's
-   * `wreqPreset`, so the geo service sees the same JA4/headers as user
-   * traffic). 4-attempt cap, 2s per endpoint. Probe results are NOT
-   * cached across sessions — proxy IPs rotate.
+   * The probe is a single GET through Chromium itself (Session.fetch via
+   * CDP `Network.loadNetworkResource`), so the geo service sees the same
+   * JA4 / headers as user traffic by definition. 4-attempt cap, 2s per
+   * endpoint. Probe results are NOT cached across sessions — proxy IPs
+   * rotate.
    *
    * @see PLAN.md §9 (relational consistency, IP/TZ/Locale axis)
-   * @see tasks/0262-ip-tz-locale-exit-consistency.md
    */
   geoConsistency?: GeoConsistencyMode;
 }
@@ -255,8 +255,8 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   const normalized = normalizeProxy(opts.proxy);
 
   // Resolve the `MatrixV1` BEFORE spawning so matrix-derived values flow
-  // into both the `--lang` flag (task 0251) and `--window-size` flag
-  // (task 0252). The matrix is otherwise read post-spawn for inject;
+  // into both the `--lang` flag and `--window-size` flag
+  //. The matrix is otherwise read post-spawn for inject;
   // deriving early is cheap (~µs, pure function) and lets us close the
   // I-5 leaks between Chromium's native network/OS-window state and the
   // JS-layer spoof.
@@ -275,7 +275,7 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   if (profileSource.autoPicked) {
     // One info-level log line so users can see what mochi inferred without
     // calling `defaultProfileForHost()` themselves. Wording is pinned by
-    // task 0272 — keep stable so docs + LLM-context blocks stay correct.
+    // — keep stable so docs + LLM-context blocks stay correct.
     // (Routed through `console.warn` to match the existing diagnostic
     // channel for `geoConsistency` / Linux-server inference; `console.info`
     // is gated by the workspace lint config — `noConsole` only allows
@@ -289,9 +289,10 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
 
   // Task 0262 — exit-IP / TZ / locale reconciliation.
   //
-  // Probe the apparent exit IP through the configured proxy (using wreq
-  // with the matrix's `wreqPreset` so the geo service sees the same JA4
-  // / headers as user traffic). Then cross-reference against
+  // Probe the apparent exit IP through the configured proxy. Post-0.7
+  // the probe runs through Chromium itself (Session.fetch via CDP
+  // `Network.loadNetworkResource`), so the geo service sees the same
+  // JA4 / headers as user traffic by definition. Cross-reference against
   // `(matrix.timezone, matrix.locale)` and apply `geoConsistency`. The
   // adjusted matrix flows into BOTH `spawnChromium` (so `--lang` reflects
   // any override) AND `Session` (so inject + the CDP `Emulation.set
@@ -303,7 +304,7 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   let adjustedMatrix = matrix;
   if (geoMode !== "off") {
     const geo = await probeExitGeo({
-      ...(normalized?.netProxy !== undefined ? { proxy: normalized.netProxy } : {}),
+      ...(normalized?.proxy !== undefined ? { proxy: normalized.proxy } : {}),
       matrix,
     });
     // Strict mode throws GeoMismatchError on real mismatch; let it
@@ -359,13 +360,13 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     // multi-locale list still flows through `matrix.languages` to the
     // inject layer's `navigator.languages` spoof; Chromium derives the
     // q-weighted `Accept-Language` value from the single `--lang` primary
-    // automatically. Task 0251.
+    // automatically.
     locale: adjustedMatrix.locale,
     // Pin OS-level outer window from the matrix's display geometry so
     // `window.outerWidth/outerHeight` (which reads from the OS window,
     // NOT the JS-spoofed `screen.*`) matches the spoof. Closes the
     // `fingerprint-scan.com` 800×600 leak under `--headless=new`.
-    // UDC fixes the same issue at `__init__.py:410-411`. Task 0252.
+    // UDC fixes the same issue at `__init__.py:410-411`.
     //
     // (`adjustedMatrix.display` === `matrix.display` since geo reconcile
     // only touches timezone/locale/languages — but we use the adjusted
@@ -395,10 +396,11 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     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 } : {}),
+    // Proxy auth is the only piece that needs explicit Session-side
+    // wiring (the `--proxy-server` flag is already on Chromium's command
+    // line above). Out-of-band `Session.fetch` traffic rides Chromium's
+    // network stack post-0.7, so it inherits the `--proxy-server` egress
+    // automatically — no per-call proxy URL needed.
     ...(normalized?.auth !== undefined ? { proxyAuth: normalized.auth } : {}),
     ...(opts.challenges !== undefined ? { challenges: opts.challenges } : {}),
   });
@@ -417,16 +419,15 @@ export const mochi = {
    * Inspect what mochi would infer about the current process environment for
    * Linux-server detection (drives `headlessMode` defaulting). Pure read of
    * `process.platform`, `process.env.DISPLAY`, `process.env.WAYLAND_DISPLAY`,
-   * `process.getuid?.()`, and the container probe paths. Task 0258.
+   * `process.getuid?.()`, and the container probe paths.
    */
   detectLinuxServerEnv: probeLinuxServerEnv,
   /**
    * Inspect which profile id `mochi.launch` would auto-pick on the current
    * host when `profile` is omitted. Pure read of `process.platform` /
    * `process.arch`. Returns `null` on unsupported hosts — the launcher
-   * throws on that path with a list of explicit profile IDs. Task 0272.
+   * throws on that path with a list of explicit profile IDs.
    *
-   * @see tasks/0271-the-linux-os-thesis.md — the strategic thesis
    * @see https://mochijs.com/docs/concepts/stealth-philosophy
    */
   defaultProfileForHost,
@@ -463,9 +464,10 @@ export function resolveHeadlessMode(
  * 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.
+ *   - `proxy`: the auth-stripped URL forwarded to the geo-probe so it
+ *     can record the egress on diagnostics. (Kept for API parity even
+ *     though the probe now rides Session.fetch + Chromium's network
+ *     stack — i.e. picks up `--proxy-server` automatically.)
  *   - `auth`: parsed credentials for the CDP auth handler. Undefined when
  *     no creds were supplied.
  *
@@ -474,7 +476,7 @@ export function resolveHeadlessMode(
 function normalizeProxy(p: LaunchOptions["proxy"]):
   | {
       server: string;
-      netProxy: string;
+      proxy: string;
       auth?: { username: string; password: string };
     }
   | undefined {
@@ -484,7 +486,7 @@ function normalizeProxy(p: LaunchOptions["proxy"]):
     const parsed = parseProxyUrl(p);
     return {
       server: parsed.server,
-      netProxy: p,
+      proxy: parsed.server,
       ...(parsed.auth !== undefined ? { auth: parsed.auth } : {}),
     };
   }
@@ -493,31 +495,13 @@ function normalizeProxy(p: LaunchOptions["proxy"]):
   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,
+    proxy: parsed.server,
     ...(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` plus the
  * meta-flag the launcher needs to decide whether to log the auto-pick
@@ -550,7 +534,7 @@ function resolveProfileSource(profile: ProfileId | ProfileV1 | undefined): {
       autoPicked: false,
     };
   }
-  // Auto-pick branch — task 0272.
+  // Auto-pick branch —
   const picked = defaultProfileForHost();
   if (picked === null) {
     throw new Error(unsupportedHostMessage(process.platform, process.arch));
@@ -598,7 +582,9 @@ function synthesizePlaceholderProfile(profile: ProfileId): ProfileV1 {
     locale: "en-US",
     languages: ["en-US", "en"],
     behavior: { hand: "right", tremor: 0.18, wpm: 60, scrollStyle: "smooth" },
-    wreqPreset: "chrome_131_linux",
+    // Deprecated — kept for one release for migration; runtime no longer
+    // reads the field. Drops in 0.8.
+    wreqPreset: "chrome_148_linux",
     userAgent:
       "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
     uaCh: {},

package/src/page/element-handle.ts

@@ -17,7 +17,6 @@
  * which is fine for a v0.2 surface.
  *
  * @see PLAN.md §8.2 / §8.3
- * @see tasks/0253-closed-shadow-piercing-locator.md
  */
 
 import type { MessageRouter } from "../cdp/router";

package/src/page/piercing.ts

@@ -33,7 +33,6 @@
  * brief — a per-page cache layer is a v0.3+ concern).
  *
  * @see PLAN.md §8.2 — `DOM.getDocument` / `DOM.resolveNode` are not forbidden
- * @see tasks/0253-closed-shadow-piercing-locator.md
  */
 
 import type { PierceDomNode } from "../cdp/types";

package/src/page/selector.ts

@@ -31,7 +31,6 @@
  * Throws `SelectorParseError` on syntactically invalid input. The matcher
  * itself never throws — unsupported nodes just don't match.
  *
- * @see tasks/0253-closed-shadow-piercing-locator.md
  * @see PLAN.md §8.2 (forbidden CDP — neither `DOM.getDocument` nor
  *   `DOM.resolveNode` is forbidden; both fine).
  */

package/src/page.ts

@@ -202,7 +202,7 @@ export interface ScreenshotOptions {
   encoding?: "binary" | "base64";
 }
 
-// ---- DX cluster: DOM storage + permissions (task 0257) ---------------------
+// ---- DX cluster: DOM storage + permissions ---------------------
 
 /**
  * Options for {@link Page.localStorage} / {@link Page.sessionStorage}
@@ -252,43 +252,61 @@ export interface DomStorage {
 /**
  * Every browser-level permission descriptor `Browser.grantPermissions` accepts.
  *
- * Pinned to the CDP `Browser.PermissionType` enum on Chromium ≥ 131 (the
- * mochi profile floor — same baseline the worker idOnly bootstrap relies on).
- * The list is verbose-on-purpose: we want a contract test to catch the day
- * Chromium adds a new permission so we can decide whether to forward it.
+ * Pinned to the CDP `Browser.PermissionType` enum on Chromium 148 (the
+ * post-0.7 profile floor — verified `2026-05-09` against the live CDP
+ * reference). The list is verbose-on-purpose: we want a contract test
+ * to catch the day Chromium adds a new permission so we can decide
+ * whether to forward it.
+ *
+ * Drift history:
+ *   - 0.7: removed `accessibilityEvents`, `captureHandle`, `flash`,
+ *     `videoCapturePanTiltZoom` (gone or renamed in 148). Added the XR
+ *     cluster (`ar`, `vr`, `handTracking`), `automaticFullscreen`,
+ *     `cameraPanTiltZoom`, `capturedSurfaceControl`, `keyboardLock`,
+ *     `pointerLock`, `localNetwork`, `localNetworkAccess`,
+ *     `loopbackNetwork`, `smartCard`, `webPrinting`.
  *
  * @see https://chromedevtools.github.io/devtools-protocol/tot/Browser/#type-PermissionType
  */
 export const ALL_BROWSER_PERMISSIONS = [
-  "accessibilityEvents",
+  "ar",
   "audioCapture",
-  "backgroundSync",
+  "automaticFullscreen",
   "backgroundFetch",
-  "captureHandle",
+  "backgroundSync",
+  "cameraPanTiltZoom",
+  "capturedSurfaceControl",
   "clipboardReadWrite",
   "clipboardSanitizedWrite",
   "displayCapture",
   "durableStorage",
-  "flash",
   "geolocation",
+  "handTracking",
   "idleDetection",
+  "keyboardLock",
   "localFonts",
+  "localNetwork",
+  "localNetworkAccess",
+  "loopbackNetwork",
   "midi",
   "midiSysex",
   "nfc",
   "notifications",
   "paymentHandler",
   "periodicBackgroundSync",
+  "pointerLock",
   "protectedMediaIdentifier",
   "sensors",
-  "storageAccess",
+  "smartCard",
   "speakerSelection",
+  "storageAccess",
   "topLevelStorageAccess",
   "videoCapture",
-  "videoCapturePanTiltZoom",
+  "vr",
   "wakeLockScreen",
   "wakeLockSystem",
   "webAppInstallation",
+  "webPrinting",
   "windowManagement",
 ] as const;
 
@@ -1030,13 +1048,12 @@ export class Page {
    * Supported selectors (see `selector.ts`): tag / id / class / attribute /
    * descendant combinator / comma-separated lists. **Not** supported:
    * `>`/`+`/`~` combinators, `:pseudo-classes`, `::pseudo-elements`, XPath.
-   * XPath is a stretch goal per task 0253 brief — TODO if a future surface
+   * XPath is a stretch goal — TODO if a future surface
    * needs it (Turnstile detection only needs CSS).
    *
    * Performance: O(N) in DOM size per call. Acceptable for v0.2; a per-page
    * cache layer is a v0.3+ concern (also called out in 0253).
    *
-   * @see tasks/0253-closed-shadow-piercing-locator.md
    * @see PLAN.md §8.2 (`DOM.getDocument` and `DOM.resolveNode` are not on the
    *   forbidden list — both fine to use here).
    */
@@ -1480,7 +1497,7 @@ function hash01(s: string): number {
   return (h >>> 0) / 0x1_0000_0000;
 }
 
-// ---- DOM storage factory (task 0257) ----------------------------------------
+// ---- DOM storage factory ----------------------------------------
 
 /**
  * Build the {@link DomStorage} returned by `Page.localStorage` /

package/src/proc.ts

@@ -15,7 +15,7 @@ import type { PipeReader, PipeWriter } from "./cdp/transport";
 /**
  * The chromium flags PLAN.md §8.6 mandates we always pass in PRODUCTION
  * (non-hermetic) mode. Trimmed against patchright's
- * `chromiumSwitchesPatch.ts:20-34` removal list (task 0256): every flag
+ * `chromiumSwitchesPatch.ts:20-34` removal list: every flag
  * here passes two tests — (a) it isn't a passive command-line bot-tell that
  * patchright explicitly drops, AND (b) we have a concrete production reason
  * to keep it (CDP transport, UI suppression that matters in headed mode,
@@ -181,7 +181,7 @@ export interface SpawnConfig {
    * integers; otherwise the flag is omitted. Sourced from
    * `matrix.display.{width,height}` by `launch.ts` — the matrix is canonical.
    *
-   * @see UDC `__init__.py:410-411`, UDC issue #2242, task 0252.
+   * @see UDC `__init__.py:410-411`, UDC issue #2242,
    */
   windowSize?: { width: number; height: number };
   /**
@@ -418,7 +418,7 @@ export function buildChromiumArgs(
   }
   // Headless dispatch.
   //
-  // `headlessMode` (task 0258) supersedes the legacy `headless: boolean` knob
+  // `headlessMode` supersedes the legacy `headless: boolean` knob
   // when both are set. When `headlessMode` is unset, fall back to the v0.1
   // mapping (`headless: true → "new"`, `false → "off"`). The launcher in
   // `launch.ts` is responsible for the env-aware default ("new" on Linux
@@ -445,7 +445,7 @@ export function buildChromiumArgs(
   // header so the network surface matches the JS-layer `navigator.language`
   // spoof (PLAN.md I-5). Pushed BEFORE `extraArgs` so a user-supplied
   // override in `args` can win on the command line if absolutely needed —
-  // Chromium honors the last-occurrence on the line for `--lang`. Task 0251.
+  // Chromium honors the last-occurrence on the line for `--lang`.
   if (cfg.locale !== undefined && cfg.locale.length > 0) {
     args.push(`--lang=${cfg.locale}`);
   }
@@ -454,7 +454,7 @@ export function buildChromiumArgs(
   // Chromium's headless 800×600 default. The matrix is canonical: when
   // `display.{width,height}` is missing or non-finite we omit the flag
   // rather than fall back to a hardcoded value (a hardcoded value would
-  // mismatch a profile that legitimately uses different dimensions). Task 0252.
+  // mismatch a profile that legitimately uses different dimensions).
   if (cfg.windowSize !== undefined) {
     const { width, height } = cfg.windowSize;
     if (
@@ -501,7 +501,6 @@ export function buildChromiumArgs(
  * surfaces only the raw stderr tail. Exported for unit tests so we can lock
  * the regexes against regressions without spawning Chromium.
  *
- * @see tasks/0259-linux-first-run-experience.md
  */
 export function diagnoseEarlyExitTail(tail: string): string {
   if (/running.*root.*without.*--no-sandbox|--no-sandbox.*required/i.test(tail)) {

package/src/proxy-auth.ts

@@ -39,8 +39,6 @@
  * handler covers both.
  *
  * @see PLAN.md §8.2 / §10
- * @see tasks/0160-proxy-auth-and-ci-fix.md
- * @see tasks/0266-fetch-fulfill-init-script.md
  */
 
 import { installInitInjector } from "./cdp/init-injector";
@@ -148,7 +146,7 @@ export interface ProxyAuthHandle {
  * shim — delegates to {@link installInitInjector} with `payloadCode: null`
  * so the proxy-auth-only call path still works for any out-of-tree caller.
  *
- * The Session no longer uses this directly (task 0266); proxy auth and
+ * The Session no longer uses this directly; proxy auth and
  * init-script delivery share a single `Fetch.enable` owner.
  *
  * Behavior (unchanged contract):