jumpy-lion 0.1.6-beta.7 → 1.0.0-beta.0

package/browser/fonts/macos-bundle/40-macos-aliases.conf

@@ -0,0 +1,515 @@
+<?xml version="1.0"?>
+<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+<!--
+  macOS family-name aliases for Linux hosts running with a macOS fingerprint.
+
+  Why: Skia consults fontconfig when resolving font family names. On a Linux
+  host without these aliases, "Helvetica" would silently substitute to
+  DejaVu Sans / Liberation Sans, producing different glyph rasters and
+  measureText() widths than real macOS. That delta survives any pixel-noise
+  patch and is the dominant signal anti-bot vendors use to detect the
+  Linux-host-spoofing-Mac case.
+
+  How it works: fontconfig reads files in /etc/fonts/conf.d/ in numeric order.
+  When a process asks for "Helvetica", the <prefer> chain below redirects to
+  the freely-licensed clone .ttf bundled in the host system, and Skia
+  rasterizes from THAT file — producing glyph metrics close to (though never
+  identical to) CoreText's output for the same name.
+
+  Prerequisites (install via apt-get on Debian/Ubuntu):
+    fonts-texgyre          (TeX Gyre Heros, Pagella, Bonum)
+    fonts-croscore         (Arimo, Tinos, Cousine — Apache 2.0 metric clones)
+    fonts-inter            (Inter — SIL OFL, SF Pro look-alike)
+    fonts-jetbrains-mono   (JetBrains Mono — Apache 2.0)
+    fonts-urw-base35       (Nimbus Sans/Roman/Mono PS, P052, URW Gothic)
+    fonts-noto-core        (Noto Sans/Serif)
+    fonts-noto-cjk         (CJK glyph coverage)
+    fonts-noto-color-emoji (Apple Color Emoji replacement)
+    fonts-liberation       (already in g2-test-actor; provides Liberation Sans/Mono/Serif)
+    fonts-dejavu-core      (already; provides DejaVu Sans Mono / DejaVu Sans)
+-->
+<fontconfig>
+
+  <!-- ============================================================
+       Helvetica family
+       ============================================================ -->
+  <alias>
+    <family>Helvetica</family>
+    <prefer>
+      <family>TeX Gyre Heros</family>
+      <family>Nimbus Sans</family>
+      <family>Arimo</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Helvetica Neue</family>
+    <prefer>
+      <family>TeX Gyre Heros</family>
+      <family>Nimbus Sans</family>
+      <family>Arimo</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       Arial / Times / Courier (cross-platform but Skia maps differ)
+       ============================================================ -->
+  <alias>
+    <family>Arial</family>
+    <prefer>
+      <family>Arimo</family>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Arial Narrow</family>
+    <prefer>
+      <family>Arimo</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Arial Black</family>
+    <prefer>
+      <family>Arimo</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Times</family>
+    <prefer>
+      <family>Tinos</family>
+      <family>Liberation Serif</family>
+      <family>Nimbus Roman</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Times New Roman</family>
+    <prefer>
+      <family>Tinos</family>
+      <family>Liberation Serif</family>
+      <family>Nimbus Roman</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Courier</family>
+    <prefer>
+      <family>Cousine</family>
+      <family>Liberation Mono</family>
+      <family>Nimbus Mono PS</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Courier New</family>
+    <prefer>
+      <family>Cousine</family>
+      <family>Liberation Mono</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       SF Pro family (San Francisco — modern macOS UI font)
+       ============================================================ -->
+  <alias>
+    <family>SF Pro</family>
+    <prefer>
+      <family>Inter</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>SF Pro Display</family>
+    <prefer>
+      <family>Inter</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>SF Pro Text</family>
+    <prefer>
+      <family>Inter</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>SF Mono</family>
+    <prefer>
+      <family>JetBrains Mono</family>
+      <family>DejaVu Sans Mono</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>-apple-system</family>
+    <prefer>
+      <family>Inter</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>BlinkMacSystemFont</family>
+    <prefer>
+      <family>Inter</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       Mac monospace family (Menlo / Monaco)
+       ============================================================ -->
+  <alias>
+    <family>Menlo</family>
+    <prefer>
+      <family>DejaVu Sans Mono</family>
+      <family>Liberation Mono</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Monaco</family>
+    <prefer>
+      <family>Liberation Mono</family>
+      <family>DejaVu Sans Mono</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       Mac sans family (Geneva / Lucida Grande / Charcoal)
+       ============================================================ -->
+  <alias>
+    <family>Geneva</family>
+    <prefer>
+      <family>Liberation Sans</family>
+      <family>DejaVu Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Lucida Grande</family>
+    <prefer>
+      <family>DejaVu Sans</family>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Charcoal</family>
+    <prefer>
+      <family>DejaVu Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Chicago</family>
+    <prefer>
+      <family>DejaVu Sans</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       Mac serif family (New York / Baskerville / Big Caslon)
+       ============================================================ -->
+  <alias>
+    <family>New York</family>
+    <prefer>
+      <family>Tinos</family>
+      <family>Liberation Serif</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Baskerville</family>
+    <prefer>
+      <family>Tinos</family>
+      <family>Liberation Serif</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Big Caslon</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Hoefler Text</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Charter</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Cochin</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Didot</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       Optima / Avenir / Futura / Gill Sans (sans variants)
+       ============================================================ -->
+  <alias>
+    <family>Optima</family>
+    <prefer>
+      <family>URW Classico</family>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Avenir</family>
+    <prefer>
+      <family>Inter</family>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Avenir Next</family>
+    <prefer>
+      <family>Inter</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Avenir Next Condensed</family>
+    <prefer>
+      <family>Inter</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Futura</family>
+    <prefer>
+      <family>URW Gothic</family>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Gill Sans</family>
+    <prefer>
+      <family>URW Gothic</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Trebuchet MS</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       Palatino / Bookman family
+       ============================================================ -->
+  <alias>
+    <family>Palatino</family>
+    <prefer>
+      <family>TeX Gyre Pagella</family>
+      <family>P052</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Bookman</family>
+    <prefer>
+      <family>TeX Gyre Bonum</family>
+      <family>URW Bookman</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Bookman Old Style</family>
+    <prefer>
+      <family>TeX Gyre Bonum</family>
+      <family>URW Bookman</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>American Typewriter</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+
+  <!-- ============================================================
+       Apple system / fallback families
+       ============================================================ -->
+  <alias>
+    <family>Apple Color Emoji</family>
+    <prefer>
+      <family>Noto Color Emoji</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Apple SD Gothic Neo</family>
+    <prefer>
+      <family>Noto Sans CJK KR</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>AppleGothic</family>
+    <prefer>
+      <family>Noto Sans CJK KR</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Hiragino Sans</family>
+    <prefer>
+      <family>Noto Sans CJK JP</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Hiragino Mincho ProN</family>
+    <prefer>
+      <family>Noto Serif CJK JP</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>PingFang SC</family>
+    <prefer>
+      <family>Noto Sans CJK SC</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>PingFang TC</family>
+    <prefer>
+      <family>Noto Sans CJK TC</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Apple Symbols</family>
+    <prefer>
+      <family>Noto Sans Symbols</family>
+      <family>Symbola</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Andale Mono</family>
+    <prefer>
+      <family>DejaVu Sans Mono</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Skia</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Marker Felt</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Chalkboard</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Chalkboard SE</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Chalkduster</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Brush Script MT</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Bradley Hand</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Snell Roundhand</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Zapfino</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Phosphate</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Trattatello</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>SignPainter</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Savoye LET</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <!-- Apple Chancery is Chrome's DEFAULT cursive family on macOS (see
+       chrome/app/resources/locale_settings_mac.grd), so this alias is not a
+       nice-to-have for pages that name the font: it decides what every
+       `font-family: cursive` on the web resolves to. Mapping it to Liberation
+       Sans made the cursive generic measure identical to the sans-serif
+       generic, which no Mac does. Z003 is URW's Zapf-Chancery clone - the same
+       visual class, and metrically distinct from every other alias here. -->
+  <alias>
+    <family>Apple Chancery</family>
+    <prefer>
+      <family>Z003</family>
+    </prefer>
+  </alias>
+  <!-- Papyrus is Chrome's default FANTASY family on macOS, same reasoning.
+       There is no free Papyrus clone, so this is an approximation in the same
+       way Helvetica -> TeX Gyre Heros is: it makes the (generic -> family)
+       relation correct and leaves the glyph metrics different from a real Mac's.
+       C059 is chosen because nothing else in this file claims it. -->
+  <alias>
+    <family>Papyrus</family>
+    <prefer>
+      <family>C059</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Bodoni 72</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Bodoni 72 Oldstyle</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Bodoni 72 Smallcaps</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Copperplate</family>
+    <prefer>
+      <family>Liberation Sans</family>
+    </prefer>
+  </alias>
+  <alias>
+    <family>Rockwell</family>
+    <prefer>
+      <family>Tinos</family>
+    </prefer>
+  </alias>
+
+</fontconfig>

package/browser/fonts/macos-bundle/README.md

@@ -0,0 +1,24 @@
+# macOS-equivalent font bundle
+
+Fontconfig aliases plus an installer that map common macOS font family names
+(Helvetica, SF Pro, Menlo, Lucida Grande, …) to freely-licensed clones, so an
+application rendering with macOS font names on a Linux host resolves to
+visually similar fonts instead of the platform defaults.
+
+## Usage (Docker)
+
+```dockerfile
+COPY browser/fonts/macos-bundle /tmp/macos-bundle
+RUN bash /tmp/macos-bundle/install.sh && rm -rf /tmp/macos-bundle
+```
+
+Verify inside the container:
+
+```bash
+fc-match Helvetica
+```
+
+## License
+
+The bundled clones are all freely licensed (Apache-2.0, SIL OFL 1.1, GUST,
+Bitstream Vera). See `install.sh` for the exact apt packages.

package/browser/fonts/macos-bundle/install.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# install.sh — install Mac-equivalent fonts and apply fontconfig aliases on
+# Debian/Ubuntu Linux hosts running cdp-crawler with a macOS fingerprint.
+#
+# Run as root (typically inside a Docker build). Idempotent — safe to re-run.
+#
+# Usage: bash install.sh [--no-cache]
+#
+# What it does:
+#   1. apt-get installs free-licensed font packages that visually match the
+#      macOS system fonts (Helvetica → TeX Gyre Heros, SF Pro → Inter, etc.).
+#   2. Copies the 40-macos-aliases.conf into /etc/fonts/conf.d/ so fontconfig
+#      remaps macOS family names to the bundled clones.
+#   3. Runs fc-cache to rebuild the system font cache so Skia (Chromium's
+#      font subsystem) sees the aliases immediately.
+#
+# Verify post-install with:  fc-match Helvetica  →  expect "qhvr.otf: ..."
+# (TeX Gyre Heros), NOT "DejaVuSans.ttf".
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKIP_CACHE=0
+for arg in "$@"; do
+    case "$arg" in
+        --no-cache) SKIP_CACHE=1 ;;
+    esac
+done
+
+# Sanity: must be Debian/Ubuntu-flavored. RHEL/Alpine need a different package set.
+if ! command -v apt-get >/dev/null 2>&1; then
+    echo "[macos-bundle] ERROR: apt-get not found — this script targets Debian/Ubuntu." >&2
+    echo "[macos-bundle] On other distros, install equivalent packages manually and copy" >&2
+    echo "[macos-bundle] 40-macos-aliases.conf into your fontconfig conf.d directory." >&2
+    exit 1
+fi
+
+# Package list. Most are present in Ubuntu 22.04+ default repos; texlive-fonts
+# packages provide TeX Gyre. We deliberately do not install *-extra packages —
+# every entry is a direct dependency of the alias chain in 40-macos-aliases.conf.
+FONT_PACKAGES=(
+    fonts-texgyre           # TeX Gyre Heros (Helvetica), Pagella (Palatino), Bonum (Bookman)
+    fonts-croscore          # Arimo (Arial), Tinos (Times), Cousine (Courier) — Apache 2.0
+    fonts-inter             # Inter — SF Pro look-alike (OFL)
+    fonts-jetbrains-mono    # JetBrains Mono — SF Mono replacement (Apache 2.0)
+    fonts-urw-base35        # Nimbus Sans/Roman/Mono PS, P052, URW Gothic, URW Bookman
+    fonts-noto-core         # Noto Sans / Noto Serif (broad Latin coverage)
+    fonts-noto-cjk          # CJK glyph coverage for Apple SD Gothic Neo / Hiragino / PingFang
+    fonts-noto-color-emoji  # Apple Color Emoji replacement
+    fonts-symbola           # Apple Symbols replacement
+    fonts-liberation        # Liberation Sans/Mono/Serif (cross-platform staple)
+    fonts-dejavu-core       # DejaVu Sans / DejaVu Sans Mono (Menlo / Lucida Grande)
+    fontconfig              # provides fc-cache, fc-match
+)
+
+echo "[macos-bundle] Installing $((${#FONT_PACKAGES[@]})) font packages via apt-get…"
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+apt-get install -y --no-install-recommends "${FONT_PACKAGES[@]}"
+
+# Drop the alias config into fontconfig's per-system conf.d. The "40-" prefix
+# places these aliases AFTER built-in family resolutions (10-/30-) but BEFORE
+# user customizations (90-).
+DEST_CONF="/etc/fonts/conf.d/40-macos-aliases.conf"
+echo "[macos-bundle] Installing fontconfig aliases → $DEST_CONF"
+install -m 0644 "$SCRIPT_DIR/40-macos-aliases.conf" "$DEST_CONF"
+
+if [[ "$SKIP_CACHE" -eq 0 ]]; then
+    echo "[macos-bundle] Rebuilding system font cache…"
+    fc-cache -f -v >/dev/null
+else
+    echo "[macos-bundle] Skipping fc-cache rebuild (--no-cache)"
+fi
+
+# Self-check: pick a few high-leverage aliases and confirm the resolution
+# returns the bundled clone, not a Linux substitute.
+echo "[macos-bundle] Verification:"
+for family in "Helvetica" "Helvetica Neue" "Times" "SF Pro" "SF Mono" "Apple Color Emoji"; do
+    resolved="$(fc-match "$family" 2>/dev/null || echo 'fc-match unavailable')"
+    echo "  $family → $resolved"
+done
+
+echo "[macos-bundle] Done."

package/dist/browser-controller.d.ts

@@ -1,6 +1,5 @@
 import { BrowserController } from 'crawlee';
-import type { LaunchBrowserOptions } from './browser-plugin.js';
-import type { CdpLauncher, LaunchReturn } from './launcher-wrap.js';
+import type { CdpLauncher, LaunchBrowserOptions, LaunchReturn } from './browser-plugin.js';
 import type { Cookie } from './page.js';
 import CdpPage from './page.js';
 export type NewPageResult = CdpPage;
@@ -9,11 +8,35 @@ LaunchBrowserOptions, // LaunchOptions
 LaunchReturn, // LaunchResult (CDP client)
 {}, // NewPageOptions (empty as there are no specific options)
 NewPageResult> {
-    private client?;
-    private reconnectAttempts;
     private hasDisconnectListener;
     private isClosing;
+    /**
+     * A SINGLE keep-alive ping loop for the whole browser socket. In flatten
+     * mode every page shares one websocket, so one ping loop (and one ws 'error'
+     * listener) covers them all - a per-page heartbeat would fan N intervals and
+     * N listeners onto the same EventEmitter.
+     */
+    private heartbeat?;
+    private heartbeatWs?;
+    private heartbeatErrorHandler?;
+    private static readonly HEARTBEAT_INTERVAL_MS;
+    /**
+     * The single browser-level CDP client. This is the ws-endpoint connection
+     * the plugin opened at launch (`_connectViaWsEndpoint`) and Crawlee handed us
+     * via `assignBrowser` - NOT a second connection. Every page is a flat CDP
+     * session multiplexed over this one socket (ADR 0003), so there is no
+     * per-page socket and no `CDP({ port })` here.
+     */
+    private get client();
     initialize(): Promise<void>;
+    /**
+     * One keep-alive ping loop for the shared browser socket. Re-bound after a
+     * socket reconnect so it follows the live ws. Idempotent.
+     * @private
+     */
+    private _attachHeartbeat;
+    /** @private */
+    private _clearHeartbeat;
     /**
      * Attach a listener to handle WebSocket disconnections.
      * @private
@@ -39,7 +62,27 @@ NewPageResult> {
      * @private
      */
     protected _newPage(maxRetries?: number): Promise<NewPageResult>;
+    /**
+     * Thin delegate to the FingerprintConfig module's post-launch path. It
+     * reuses the once-per-launch profile selection (stamped by the plugin's
+     * pre-launch native path) or selects here for the system-Chrome fallback,
+     * then drives the JS fingerprint injection on the new page. The pre-vs-post
+     * decision and the PROFILE_SELECTION_KEY handshake live inside that module.
+     */
     private _maybeOverrideFingerprint;
+    /**
+     * Records the launch-time inputs the saveSession() helper later needs to read
+     * off the page - fingerprintConfig, fingerprintOptions, resolvedLocale, fingerprint,
+     * userDataDir, proxyUrl, and the sessionBundle (if any).
+     * @private
+     */
+    private _recordLaunchSnapshot;
+    /**
+     * Replays cookies + per-origin localStorage/sessionStorage from the sessionBundle
+     * onto a fresh page before any navigation happens.
+     * @private
+     */
+    private _maybeRestoreSession;
     /**
      * Sets cookies on the given page.
      * @private