@mochi.js/core 0.3.0 → 0.8.0

package/src/page.ts

@@ -38,7 +38,6 @@ import type {
   PierceDomNode,
   RemoteObject,
 } from "./cdp/types";
-import { NotImplementedError } from "./errors";
 import { ElementHandle } from "./page/element-handle";
 import { findPiercingMatches } from "./page/piercing";
 import { parseSelector } from "./page/selector";
@@ -92,12 +91,16 @@ export interface PageInit {
   /** Initial URL (typically "about:blank"). */
   initialUrl: string;
   /**
-   * Identifier returned by `Page.addScriptToEvaluateOnNewDocument` when the
-   * inject payload was installed at session-newPage time. Tracked here so
-   * `Page.close()` can call `Page.removeScriptToEvaluateOnNewDocument` —
-   * required by PLAN.md §8.4 to keep the per-target identifier list bounded.
+   * Legacy field — preserved as optional for any out-of-tree caller that
+   * still constructs a Page with it. Task 0266 retired the per-page
+   * `Page.addScriptToEvaluateOnNewDocument` install in favour of the
+   * session-level `Fetch.fulfillRequest` body splice; the field is no
+   * longer set by `Session.newPage()` and the legacy
+   * `removeScriptToEvaluateOnNewDocument` cleanup in `close()` is a no-op
+   * when this is unset.
    *
-   * Optional: zero-spoofing test setups (or future no-inject paths) may omit.
+   * @deprecated retained only for backward compatibility; remove after a
+   * full deprecation cycle.
    */
   injectScriptIdentifier?: string;
   /**
@@ -156,6 +159,170 @@ export interface HumanScrollOptions {
   duration?: number;
 }
 
+/**
+ * Options for `Page.screenshot`. Maps directly onto CDP `Page.captureScreenshot`
+ * params with a thin compatibility layer for `fullPage` (which CDP doesn't
+ * model directly — we synthesize it from `Page.getLayoutMetrics` +
+ * `Emulation.setDeviceMetricsOverride`).
+ *
+ * @see PLAN.md §8.2 — `Page.captureScreenshot` is NOT on the forbidden list
+ *      (only `Runtime.enable` and `Page.createIsolatedWorld` are).
+ */
+export interface ScreenshotOptions {
+  /** Image format. Default `"png"`. */
+  format?: "png" | "jpeg" | "webp";
+  /**
+   * Compression quality, 0..100. JPEG/WebP only — silently ignored for PNG by
+   * the CDP layer (we still pass it through; CDP just drops it).
+   */
+  quality?: number;
+  /**
+   * Capture beyond the visible viewport — i.e. the full document height.
+   * Implementation: `Page.getLayoutMetrics` for content size, override the
+   * device metrics to that size via `Emulation.setDeviceMetricsOverride`,
+   * capture, then `Emulation.clearDeviceMetricsOverride` to restore (always,
+   * even on capture failure).
+   */
+  fullPage?: boolean;
+  /**
+   * Capture only a rectangular region (CSS pixels). Mutually exclusive with
+   * `fullPage` — if both are set, `clip` wins (CDP semantics).
+   */
+  clip?: { x: number; y: number; width: number; height: number; scale?: number };
+  /**
+   * Render the page background as transparent (PNG only). For JPEG this is a
+   * no-op since JPEG has no alpha channel.
+   */
+  omitBackground?: boolean;
+  /**
+   * Output encoding. `"binary"` (default) returns `Uint8Array`; `"base64"`
+   * returns the raw CDP base64 string. The discriminated overloads of
+   * `Page.screenshot` narrow the return type accordingly.
+   */
+  encoding?: "binary" | "base64";
+}
+
+// ---- DX cluster: DOM storage + permissions ---------------------
+
+/**
+ * Options for {@link Page.localStorage} / {@link Page.sessionStorage}
+ * accessors. Both default to the page's main-frame origin (read at call time
+ * from `window.location.origin`); pass `origin` to read/write a different
+ * frame's storage explicitly.
+ */
+export interface DomStorageOptions {
+  /**
+   * Origin to scope the storage read/write to (e.g. `"https://example.com"`).
+   * Default: the page's current main-frame origin.
+   *
+   * Required when the call must hit a *different* origin's storage (e.g.
+   * cross-origin warm-session restore). If the page hasn't navigated yet
+   * (origin = `"about:blank"`), an explicit `origin` is required.
+   */
+  origin?: string;
+}
+
+/**
+ * The shape returned by {@link Page.localStorage} / {@link Page.sessionStorage}.
+ * Both accessors return the same surface — the only difference is the
+ * `isLocalStorage` flag CDP receives under the hood.
+ *
+ * Backed by `DOMStorage.getDOMStorageItems` / `DOMStorage.setDOMStorageItem`.
+ * Per CDP, the response shape for `getDOMStorageItems` is
+ * `{ entries: [string, string][] }` — we collapse that to a `Record` for
+ * Bun-native ergonomics.
+ *
+ * @see https://chromedevtools.github.io/devtools-protocol/tot/DOMStorage/
+ */
+export interface DomStorage {
+  /**
+   * Read every key/value pair currently in the (local|session)Storage of the
+   * scoped origin. Default scope: the page's main-frame origin at call time.
+   */
+  get(opts?: DomStorageOptions): Promise<Record<string, string>>;
+  /**
+   * Write each key in `items` to the scoped origin's storage. Existing keys
+   * not mentioned in `items` are left untouched (this is `Object.assign`
+   * semantics, not `replace`). To clear, set the key explicitly to `""` or
+   * fetch via {@link get} → mutate → call {@link set} with the union.
+   */
+  set(items: Record<string, string>, opts?: DomStorageOptions): Promise<void>;
+}
+
+/**
+ * Every browser-level permission descriptor `Browser.grantPermissions` accepts.
+ *
+ * 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 = [
+  "ar",
+  "audioCapture",
+  "automaticFullscreen",
+  "backgroundFetch",
+  "backgroundSync",
+  "cameraPanTiltZoom",
+  "capturedSurfaceControl",
+  "clipboardReadWrite",
+  "clipboardSanitizedWrite",
+  "displayCapture",
+  "durableStorage",
+  "geolocation",
+  "handTracking",
+  "idleDetection",
+  "keyboardLock",
+  "localFonts",
+  "localNetwork",
+  "localNetworkAccess",
+  "loopbackNetwork",
+  "midi",
+  "midiSysex",
+  "nfc",
+  "notifications",
+  "paymentHandler",
+  "periodicBackgroundSync",
+  "pointerLock",
+  "protectedMediaIdentifier",
+  "sensors",
+  "smartCard",
+  "speakerSelection",
+  "storageAccess",
+  "topLevelStorageAccess",
+  "videoCapture",
+  "vr",
+  "wakeLockScreen",
+  "wakeLockSystem",
+  "webAppInstallation",
+  "webPrinting",
+  "windowManagement",
+] as const;
+
+/** A single entry from {@link ALL_BROWSER_PERMISSIONS}. */
+export type BrowserPermission = (typeof ALL_BROWSER_PERMISSIONS)[number];
+
+/** Options for {@link Page.grantAllPermissions}. */
+export interface GrantAllPermissionsOptions {
+  /**
+   * Origin to grant permissions to. Default: the page's current main-frame
+   * origin (read at call time). When `about:blank`, an explicit `origin` is
+   * required — `Browser.grantPermissions` rejects opaque origins.
+   */
+  origin?: string;
+}
+
 export class Page {
   private readonly router: MessageRouter;
   private readonly targetId: string;
@@ -194,6 +361,10 @@ export class Page {
    * — see PLAN.md I-5: behavioral parameters come from MatrixV1.profile.behavior).
    */
   private cursor: { x: number; y: number };
+  /** localStorage namespace returned by the {@link localStorage} getter. */
+  private readonly localStorageJar: DomStorage;
+  /** sessionStorage namespace returned by the {@link sessionStorage} getter. */
+  private readonly sessionStorageJar: DomStorage;
 
   constructor(init: PageInit) {
     this.router = init.router;
@@ -204,6 +375,10 @@ export class Page {
     this.behavior = init.behavior ?? DEFAULT_BEHAVIOR_PROFILE;
     this.seed = init.seed ?? "default";
     this.cursor = init.initialCursor ?? { x: 0, y: 0 };
+    // Bind both DOM-storage namespaces once. The `isLocalStorage` flag
+    // routes the same plumbing to local vs session storage on the CDP side.
+    this.localStorageJar = createDomStorage(this, true);
+    this.sessionStorageJar = createDomStorage(this, false);
     this.subscribeFrameTopology();
   }
 
@@ -365,6 +540,67 @@ export class Page {
     return result.cookies;
   }
 
+  /**
+   * Per-origin localStorage accessor — `get()` and `set(items)`. Backed by
+   * `DOMStorage.getDOMStorageItems` / `DOMStorage.setDOMStorageItem`. Frame
+   * scope defaults to the page's current main-frame origin; pass
+   * `{ origin }` to target a different frame's storage. See {@link DomStorage}.
+   *
+   * Use cases (per `docs/audits/nodriver.md` LOW finding 3):
+   *   - "returning visitor" warming: seed `lastVisit`, A/B-test bucket,
+   *     consent-banner dismissal.
+   *   - Capture + replay across runs by serializing the `Record` to disk.
+   *
+   * Sister surface: {@link sessionStorage} — same shape, hits sessionStorage
+   * via the `isLocalStorage: false` CDP flag.
+   */
+  get localStorage(): DomStorage {
+    return this.localStorageJar;
+  }
+
+  /**
+   * Per-origin sessionStorage accessor. Same shape as {@link localStorage}
+   * but hits sessionStorage via `DOMStorage.getDOMStorageItems` /
+   * `DOMStorage.setDOMStorageItem` with `isLocalStorage: false`. Note
+   * sessionStorage is per-tab — values written here vanish when the page is
+   * closed, exactly as in a regular browsing session.
+   */
+  get sessionStorage(): DomStorage {
+    return this.sessionStorageJar;
+  }
+
+  /**
+   * Grant every permission `Browser.grantPermissions` accepts (the full
+   * descriptor list pinned by {@link ALL_BROWSER_PERMISSIONS}) to the
+   * scoped origin. Defaults to the page's current main-frame origin; pass
+   * `{ origin }` to grant explicitly.
+   *
+   * Pairs with R-036 (the per-permission `navigator.permissions.query()`
+   * spoof in `@mochi.js/inject/src/modules/permissions.ts`): this method
+   * grants ALL at the *browser* level (so the page never sees a permission
+   * prompt), but the page-side `query()` matrix still returns whatever
+   * `matrix.uaCh["permissions-defaults"]` says. The two surfaces are
+   * orthogonal — the inject module decides what the page *sees*; this method
+   * decides what the browser *enforces*.
+   *
+   * Throws when the page hasn't navigated yet (`about:blank` resolves to no
+   * usable origin) and no `origin` was passed explicitly — the CDP method
+   * rejects opaque origins.
+   *
+   * @see docs/audits/nodriver.md LOW finding 4 (`Browser.grant_all_permissions`).
+   */
+  async grantAllPermissions(opts: GrantAllPermissionsOptions = {}): Promise<void> {
+    this.assertOpen();
+    const origin = opts.origin ?? (await this.resolveOrigin("grantAllPermissions"));
+    // Browser.grantPermissions runs on the ROOT browser target — it's not a
+    // page-scoped method. The router's `sessionId` defaults to the root
+    // browser target when omitted, which is exactly what we want here.
+    await this.router.send("Browser.grantPermissions", {
+      permissions: [...ALL_BROWSER_PERMISSIONS],
+      origin,
+    });
+  }
+
   /**
    * Install an additional main-world script that runs on every new document
    * via `Page.addScriptToEvaluateOnNewDocument({ runImmediately: true,
@@ -812,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).
    */
@@ -875,8 +1110,95 @@ export class Page {
     return handles;
   }
 
-  screenshot(_opts?: unknown): Promise<Uint8Array> {
-    return Promise.reject(new NotImplementedError("page.screenshot"));
+  /**
+   * Capture a screenshot of the page via CDP `Page.captureScreenshot`.
+   *
+   * Default: PNG-encoded `Uint8Array` of the visible viewport. Pass
+   * `fullPage: true` to capture beyond the viewport (we round-trip through
+   * `Emulation.setDeviceMetricsOverride` and restore via
+   * `Emulation.clearDeviceMetricsOverride` afterwards — guaranteed even on
+   * capture failure). Pass `encoding: "base64"` to skip the base64 → bytes
+   * decode and get the raw CDP string back.
+   *
+   * Out of scope at v0.2 (tracked separately):
+   *   - Element-bounded screenshot (`{ element: handle }`) — needs
+   *     `DOM.getBoxModel` integration.
+   *   - PDF generation — `Page.printToPDF` lives in its own brief.
+   *
+   * @see PLAN.md §8.2 — `Page.captureScreenshot` is permitted; only
+   *      `Runtime.enable` and `Page.createIsolatedWorld` are forbidden.
+   */
+  screenshot(opts: ScreenshotOptions & { encoding: "base64" }): Promise<string>;
+  screenshot(opts?: ScreenshotOptions & { encoding?: "binary" }): Promise<Uint8Array>;
+  async screenshot(opts: ScreenshotOptions = {}): Promise<Uint8Array | string> {
+    this.assertOpen();
+    const format = opts.format ?? "png";
+    // CDP `Page.captureScreenshot` params. We pass `captureBeyondViewport`
+    // for fullPage *in addition to* the device-metrics override below — the
+    // override changes the layout viewport for the capture, while
+    // `captureBeyondViewport` lets the renderer paint past the visible area
+    // for the duration of the capture (belt-and-braces; either alone has
+    // edge cases on long pages).
+    const params: Record<string, unknown> = { format };
+    if (opts.quality !== undefined && (format === "jpeg" || format === "webp")) {
+      params.quality = opts.quality;
+    }
+    if (opts.clip !== undefined) {
+      // CDP requires `scale` — default 1 if caller didn't set it.
+      params.clip = { ...opts.clip, scale: opts.clip.scale ?? 1 };
+    }
+    if (opts.omitBackground === true) {
+      params.omitBackground = true;
+    }
+
+    // fullPage round-trip. We capture the layout metrics first, then size
+    // the device viewport up to the content size, capture, then clear the
+    // override. The `try/finally` is load-bearing — if `captureScreenshot`
+    // throws (e.g. target detached mid-capture) we still need to restore
+    // the viewport so subsequent calls don't see a frozen oversized layout.
+    let restoreOverride = false;
+    if (opts.fullPage === true && opts.clip === undefined) {
+      const metrics = await this.send<{
+        contentSize: { width: number; height: number };
+        layoutViewport: { clientWidth: number; clientHeight: number };
+      }>("Page.getLayoutMetrics");
+      const width = Math.ceil(metrics.contentSize.width);
+      const height = Math.ceil(metrics.contentSize.height);
+      await this.send("Emulation.setDeviceMetricsOverride", {
+        width,
+        height,
+        deviceScaleFactor: 0,
+        mobile: false,
+      });
+      restoreOverride = true;
+      params.captureBeyondViewport = true;
+    }
+
+    let result: { data: string };
+    try {
+      result = await this.send<{ data: string }>("Page.captureScreenshot", params);
+    } finally {
+      if (restoreOverride) {
+        // Always clear, even if capture threw. Best-effort: if the target is
+        // gone the clear will fail and we swallow it — the page is unusable
+        // anyway and the override dies with the target.
+        try {
+          await this.send("Emulation.clearDeviceMetricsOverride");
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    const encoding = opts.encoding ?? "binary";
+    if (encoding === "base64") {
+      return result.data;
+    }
+    // Decode base64 → bytes via Bun-native `Buffer.from`. The Buffer is a
+    // Uint8Array subclass; we slice into a plain Uint8Array view backed by
+    // the same memory so the public type is the standard one.
+    const buf = Buffer.from(result.data, "base64");
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
   }
 
   // ---- internals --------------------------------------------------------------
@@ -886,6 +1208,52 @@ export class Page {
     return this.router.send<T>(method, params, { sessionId: this.sessionId });
   }
 
+  /**
+   * Resolve the page's main-frame origin via `Runtime.callFunctionOn` against
+   * the document objectId. Used by {@link grantAllPermissions} and the DOM
+   * storage namespaces when the caller didn't pass an explicit `origin`.
+   *
+   * Throws with a precise diagnostic when the origin is opaque
+   * (`about:blank` / `data:` URLs) — the consumers can't fall back to
+   * "current page" because there's nothing meaningful to scope.
+   */
+  private async resolveOrigin(callerName: string): Promise<string> {
+    const docId = await this.documentObjectId();
+    const r = await this.send<{ result: RemoteObject }>("Runtime.callFunctionOn", {
+      objectId: docId,
+      functionDeclaration:
+        "function() { return (this.defaultView || window).location && (this.defaultView || window).location.origin || ''; }",
+      returnByValue: true,
+    });
+    const v = r.result.value;
+    if (typeof v !== "string" || v.length === 0 || v === "null") {
+      throw new Error(
+        `[mochi] page.${callerName}: page origin is opaque (likely about:blank). Pass { origin } explicitly.`,
+      );
+    }
+    return v;
+  }
+
+  /**
+   * Module-private accessor used by {@link createDomStorage}. Mirrors the
+   * cookie-jar plumbing pattern on Session — the factory lives in module
+   * scope so its return type can be the public {@link DomStorage} interface
+   * without leaking implementation onto the Page surface.
+   *
+   * @internal
+   */
+  _internalDomStoragePlumbing(): {
+    send: <T>(method: string, params?: unknown) => Promise<T>;
+    resolveOrigin: (caller: string) => Promise<string>;
+    assertOpen: () => void;
+  } {
+    return {
+      send: <T>(method: string, params?: unknown) => this.send<T>(method, params),
+      resolveOrigin: (caller: string) => this.resolveOrigin(caller),
+      assertOpen: () => this.assertOpen(),
+    };
+  }
+
   /** Subscribe to frame events to keep `currentUrl` and `mainFrameId` fresh. */
   private subscribeFrameTopology(): void {
     this.router.on("Page.frameNavigated", (params, sessionId) => {
@@ -1128,3 +1496,54 @@ function hash01(s: string): number {
   }
   return (h >>> 0) / 0x1_0000_0000;
 }
+
+// ---- DOM storage factory ----------------------------------------
+
+/**
+ * Build the {@link DomStorage} returned by `Page.localStorage` /
+ * `Page.sessionStorage`. Bound to one Page instance via
+ * {@link Page._internalDomStoragePlumbing}. Module-private; the public surface
+ * is the interface — instances are only created by the Page constructor.
+ *
+ * `isLocalStorage` flag picks the CDP storage backing:
+ *   - `true`  → `localStorage`  (the persistent per-origin store).
+ *   - `false` → `sessionStorage` (the per-tab transient store).
+ *
+ * @internal
+ */
+function createDomStorage(page: Page, isLocalStorage: boolean): DomStorage {
+  const { send, resolveOrigin, assertOpen } = page._internalDomStoragePlumbing();
+  const callerName = isLocalStorage ? "localStorage" : "sessionStorage";
+  return {
+    async get(opts: DomStorageOptions = {}) {
+      assertOpen();
+      const securityOrigin = opts.origin ?? (await resolveOrigin(`${callerName}.get`));
+      const result = await send<{ entries: Array<[string, string]> }>(
+        "DOMStorage.getDOMStorageItems",
+        { storageId: { securityOrigin, isLocalStorage } },
+      );
+      // CDP returns `[ [k, v], ... ]`. Collapse to a Record for ergonomics.
+      const out: Record<string, string> = {};
+      for (const entry of result.entries) {
+        const k = entry[0];
+        const v = entry[1];
+        if (typeof k === "string" && typeof v === "string") out[k] = v;
+      }
+      return out;
+    },
+    async set(items: Record<string, string>, opts: DomStorageOptions = {}) {
+      assertOpen();
+      const securityOrigin = opts.origin ?? (await resolveOrigin(`${callerName}.set`));
+      // CDP's `setDOMStorageItem` takes one key/value at a time. We fan out
+      // sequentially so a partial failure (e.g. a too-large value) surfaces
+      // with the offending key in the error frame.
+      for (const [k, v] of Object.entries(items)) {
+        await send("DOMStorage.setDOMStorageItem", {
+          storageId: { securityOrigin, isLocalStorage },
+          key: k,
+          value: v,
+        });
+      }
+    },
+  };
+}

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,
@@ -108,8 +108,35 @@ export interface SpawnConfig {
   binary: string;
   /** User-supplied extra flags appended after the defaults. Null to skip. */
   extraArgs?: readonly string[];
-  /** Run headless via Chromium's modern `--headless=new` flag. */
+  /**
+   * Legacy boolean knob. `true` → emit `--headless=new`. Retained for
+   * backward compatibility with v0.1 callers. New code should set
+   * {@link headlessMode} instead — it carries strictly more information
+   * (`"new" | "legacy" | "off"`) and supersedes this field when both are set.
+   */
   headless: boolean;
+  /**
+   * Headless dispatch mode. Takes precedence over {@link headless} when set.
+   *
+   *   - `"new"`    → emit `--headless=new` (modern headless: full rendering,
+   *                  near-byte-identical to headful for fingerprinting).
+   *   - `"legacy"` → emit bare `--headless` (legacy headless code path; more
+   *                  detectable but useful for parity with older tooling).
+   *   - `"off"`    → emit no headless flag (run headful — requires a display
+   *                  server / xvfb).
+   *
+   * Resolution at the launch layer:
+   *
+   *   1. If the caller passes `headlessMode` explicitly, it wins.
+   *   2. Else if the caller passes the legacy `headless: true | false`, it
+   *      maps to `"new"` / `"off"` respectively.
+   *   3. Else the launcher inspects the live env: Linux without DISPLAY /
+   *      WAYLAND_DISPLAY → `"new"`; everywhere else → `"off"`.
+   *
+   * @see tasks/0258 (Linux server env auto-detection)
+   * @see docs/getting-started/linux-server.md
+   */
+  headlessMode?: "new" | "legacy" | "off";
   /** Optional proxy server, e.g. "http://host:port" or "socks5://host:port". */
   proxy?: string;
   /**
@@ -154,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 };
   /**
@@ -389,12 +416,28 @@ export function buildChromiumArgs(
   if (cfg.hermetic === true) {
     args.push(...HERMETIC_ONLY_CHROMIUM_FLAGS);
   }
-  if (cfg.headless) {
-    // Modern headless mode (matches stable Chrome behavior more closely than
-    // legacy --headless). The `=new` is critical — old `--headless` is
-    // detectable.
+  // Headless dispatch.
+  //
+  // `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
+  // server, "off" on dev workstation with DISPLAY); by the time we reach
+  // here, `headlessMode` is the resolved decision.
+  //
+  // `--headless=new` is the modern code path (full rendering, near-byte-
+  // identical to headful for fingerprinting). The bare `--headless` is the
+  // legacy mode — separate, more-detectable code path; we expose it for
+  // parity-with-older-tooling needs but never default to it. Source-cited
+  // from Chromium HeadlessShell `--headless=new` migration notes (Chromium
+  // M118+).
+  const mode = cfg.headlessMode ?? (cfg.headless ? "new" : "off");
+  if (mode === "new") {
     args.push("--headless=new");
+  } else if (mode === "legacy") {
+    args.push("--headless");
   }
+  // mode === "off" → no headless flag.
   if (cfg.proxy !== undefined && cfg.proxy.length > 0) {
     args.push(`--proxy-server=${cfg.proxy}`);
   }
@@ -402,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}`);
   }
@@ -411,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 (
@@ -458,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)) {