jumpy-lion 0.1.6-beta.9 → 1.0.0-beta.4

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

@@ -0,0 +1,136 @@
+#!/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 the free-licensed font packages the generated faces are
+#      built from, plus the vendored ones apt cannot supply.
+#   2. Installs generated/*.ttf — one real font file per macOS family, named as
+#      that family and carrying its own per-character advances (see
+#      build-metric-fonts.py). These replace most of what the alias file used to
+#      do, and they are why families no longer collapse onto shared clones.
+#   3. Copies 41-macos-remaining.conf into /etc/fonts/conf.d/ for what a Latin
+#      donor cannot stand in for: the CJK/symbol/emoji faces and the generics.
+#   4. Runs fc-cache to rebuild the system font cache so Skia (Chromium's
+#      font subsystem) sees everything immediately.
+#
+# Verify post-install with:  fc-match Copperplate  →  expect Copperplate itself,
+# not Liberation Sans. A macOS family that answers with a clone name means its
+# generated face is missing and it has fallen back to the old shared-clone
+# behaviour, where 54 families measured as 19 distinct faces.
+
+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-crosextra-carlito # Carlito (Calibri) — the narrow sans; measured 247.37
+                            # against Gill Sans's 245.89, where Arimo was 17.8 off
+    fonts-crosextra-caladea # Caladea (Cambria) — stands in for Apple Chancery at
+                            # 246.90 against 250.45. Its job is as much to be a
+                            # DIFFERENT file from the serif clone: Apple Chancery
+                            # is Chrome's default CURSIVE family on macOS, so
+                            # pointing it at Tinos made the cursive generic
+                            # measure identically to serif, which no Mac does
+    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
+# One package at a time, tolerating misses. The list targets Ubuntu, and a few of
+# these names do not exist on Debian trixie - where a single unknown package
+# fails the whole apt invocation and takes the install with it. A miss is
+# survivable now that the generated faces in generated/ carry the metrics: the
+# apt packages are donors for the GENERATOR, not the runtime resolution path.
+for pkg in "${FONT_PACKAGES[@]}"; do
+    apt-get install -y --no-install-recommends "$pkg" \
+        || echo "[macos-bundle] skipped unavailable package: $pkg"
+done
+
+# 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-).
+# Fonts that apt cannot supply: Georgia's only free metric clone (Gelasio) and
+# Impact's usual stand-in (Anton). Neither is packaged in Debian/Ubuntu, so both
+# ship in vendor/ - see vendor/README.md.
+# Installed before the alias file so fc-cache below sees it in one pass.
+VENDOR_DIR="$SCRIPT_DIR/vendor"
+if [[ -d "$VENDOR_DIR" ]]; then
+    echo "[macos-bundle] Installing vendored fonts → /usr/local/share/fonts/macos-bundle/"
+    install -d /usr/local/share/fonts/macos-bundle
+    find "$VENDOR_DIR" -type f \( -name '*.ttf' -o -name '*.otf' \) \
+        -exec install -m 0644 {} /usr/local/share/fonts/macos-bundle/ \;
+fi
+
+# The generated per-family faces. One file per macOS family, named as that
+# family, with that family's own advances written into hmtx. They must land in a
+# directory fontconfig scans and BEFORE the cache is rebuilt below.
+GENERATED_DIR="$SCRIPT_DIR/generated"
+if [[ -d "$GENERATED_DIR" ]]; then
+    count=$(find "$GENERATED_DIR" -name '*.ttf' | wc -l | tr -d ' ')
+    echo "[macos-bundle] Installing $count generated macOS faces → /usr/local/share/fonts/macos-metrics/"
+    install -d /usr/local/share/fonts/macos-metrics
+    find "$GENERATED_DIR" -type f -name '*.ttf' \
+        -exec install -m 0644 {} /usr/local/share/fonts/macos-metrics/ \;
+else
+    echo "[macos-bundle] WARNING: generated/ is missing - macOS families will fall back to shared clones." >&2
+fi
+
+# The old 40-macos-aliases.conf is removed rather than left in place: its
+# <match target="pattern"> rewrites are authoritative, so a stale copy would
+# redirect every generated family straight back to the shared clone it replaced.
+rm -f /etc/fonts/conf.d/40-macos-aliases.conf
+
+DEST_CONF="/etc/fonts/conf.d/41-macos-remaining.conf"
+echo "[macos-bundle] Installing remaining fontconfig aliases → $DEST_CONF"
+install -m 0644 "$SCRIPT_DIR/41-macos-remaining.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" "Times" "Georgia" "Palatino" "Verdana" "Copperplate" "Optima" "Zapfino" "Monaco"; do
+    resolved="$(fc-match "$family" 2>/dev/null || echo 'fc-match unavailable')"
+    echo "  $family → $resolved"
+done
+
+echo "[macos-bundle] Done."

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

@@ -0,0 +1,30 @@
+# Vendored fonts
+
+Font files that are **not** packaged in Debian/Ubuntu and therefore cannot come
+from `apt-get` like the rest of the bundle.
+They are committed here rather than downloaded by `install.sh` so an image build
+stays reproducible and works without network access to a third-party host.
+
+## gelasio
+
+Metric-compatible clone of **Georgia**, needed because Georgia is on macOS (and
+on the binary's canvas font allowlist for the `apple_metal` family) while no
+Debian package clones it.
+Without it, a page asking for Georgia fell through to the fontconfig serif
+default and measured 249.85px where a real Mac measures 272.31px for the same
+string - a 22px, trivially detectable gap on one of the most commonly requested
+web fonts.
+
+| file | sha256 |
+| --- | --- |
+| `Gelasio-VariableFont_wght.ttf` | `4daecea457258c9ebeb8bc99ed3fd24353618bfad3ea4b93fa0b5d0468fc04e4` |
+| `Gelasio-Italic-VariableFont_wght.ttf` | `52559e845a4d33514e5f93bb9ae7dbeae1894a53f2c565a15f18af40cd337c09` |
+
+Upstream: <https://github.com/SorkinType/Gelasio>, redistributed via
+[google/fonts `ofl/gelasio`](https://github.com/google/fonts/tree/main/ofl/gelasio).
+Licence: SIL Open Font License 1.1 - see `gelasio/OFL.txt`.
+
+To refresh, re-download the same two files from google/fonts, update the hashes
+above, and re-run the alias verification
+(`test/docker-linux/font-survey.mjs` + `font-match.mjs`) - a new upstream release
+can change the advance width, which is the whole reason this file is here.

package/browser/fonts/macos-bundle/vendor/anton/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Anton Project Authors (https://github.com/googlefonts/AntonFont.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/browser/fonts/macos-bundle/vendor/gelasio/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Gelasio Project Authors (https://github.com/SorkinType/Gelasio)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/browser/fonts/macos-bundle/verify-metric-fonts.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Check the generated faces against the macOS capture they were built from.
+
+Reads the font files directly, so it verifies the generator without a browser,
+a container launch or a fontconfig lookup in the way. Run it after regenerating,
+and in CI if the fonts ever move into one.
+
+    python3 verify-metric-fonts.py \
+        --advances char-advances-macos-chrome151.json \
+        --generated generated/
+
+Exit status is non-zero if any face is off by more than the tolerance, with no
+exceptions: the generator screens donors so that every captured character has
+its own glyph and can therefore hold its own advance. That screen exists because
+21 of the measured macOS faces give U+00A0 a different advance from U+0020, and
+a donor that maps both to one glyph drops the difference silently.
+"""
+
+import argparse
+import json
+import os
+import sys
+
+from fontTools.pens.boundsPen import BoundsPen
+from fontTools.ttLib import TTFont
+
+# 0.5% is below what a measureText() comparison can resolve at the sizes pages
+# use; the floor is the rounding of each advance to integer font units.
+TOLERANCE = 0.005
+
+# The ink box gets its own, looser floor, and the reason is arithmetic rather
+# than indulgence. An advance error is measured against the advance, which is
+# most of an em; a box edge is measured against the SPAN of that box, and a
+# period's span is a few percent of an em - so the same half-unit of rounding
+# that is 0.02% on an advance is 0.4% on a full stop. Measured across the
+# generated bundle the median is 0.02% and the worst case is exactly that: the
+# period's xMax.
+INK_TOLERANCE = 0.01
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--advances", required=True)
+    parser.add_argument("--generated", required=True)
+    parser.add_argument("--inkbox", default="",
+                        help="per-character ink box capture; when given, every "
+                             "glyph's bounding box is checked as well as its advance")
+    args = parser.parse_args()
+
+    with open(args.advances, encoding="utf-8") as handle:
+        advances = json.load(handle)["advances"]
+    ink_capture = {}
+    if args.inkbox:
+        with open(args.inkbox, encoding="utf-8") as handle:
+            payload = json.load(handle)
+        if payload.get("fields") != ["width", "left", "right", "ascent", "descent"]:
+            sys.exit(f"--inkbox field order is {payload.get('fields')}, expected "
+                     "['width', 'left', 'right', 'ascent', 'descent']")
+        ink_capture = payload["metrics"]
+    with open(os.path.join(args.generated, "manifest.json"), encoding="utf-8") as handle:
+        manifest = json.load(handle)
+
+    checked = 0
+    worst_overall = 0.0
+    worst_ink = 0.0
+    worst_ink_where = ""
+    ink_failures = []
+    unexpressible = []
+    failures = []
+    for key, info in sorted(manifest.items()):
+        family, style = key.rsplit(" ", 1)
+        # The system face is captured under the name a page can reach, and built
+        # under the name Blink resolves system-ui to.
+        source = "system-ui" if family == "BlinkMacSystemFont" else family
+        # The capture keys a style exactly as CSS spells it. Mapping every
+        # non-regular style to "|bold" compared each italic face against the
+        # BOLD advances and reported 60 false failures.
+        suffix = {"regular": "", "bold": "|bold", "italic": "|italic",
+                  "bolditalic": "|bold italic"}.get(style)
+        if suffix is None:
+            print(f"  ERROR: {key} - unknown style {style!r}")
+            failures.append(key)
+            continue
+        row = advances.get(f"{source}{suffix}")
+        if not row or row.get("unset"):
+            continue
+
+        font = TTFont(os.path.join(args.generated, info["file"]), lazy=True)
+        upem = font["head"].unitsPerEm
+        cmap = font.getBestCmap()
+        hmtx = font["hmtx"]
+
+        # Ink boxes, read back from the file the same way a rasteriser reads
+        # them: true bounds including curve extrema, so the check does not pass
+        # on a control-point box that overstates every curved glyph.
+        ink_row = ink_capture.get(f"{source}{suffix}") if ink_capture else None
+        if ink_row and not ink_row.get("unset"):
+            glyph_set = font.getGlyphSet()
+            ink_off = []
+            for codepoint, box in ink_row.items():
+                glyph = cmap.get(int(codepoint))
+                if glyph is None or not isinstance(box, list) or len(box) != 5:
+                    continue
+                _advance, left, right, ascent, descent = box
+                want = (-left * upem, -descent * upem, right * upem, ascent * upem)
+                span = max(want[2] - want[0], want[3] - want[1])
+                if span <= 0:
+                    continue  # blank on the Mac; the generator clears these
+                pen = BoundsPen(glyph_set)
+                glyph_set[glyph].draw(pen)
+                if pen.bounds is None:
+                    # The Mac paints something here and the donor has no outline
+                    # for it at all - Webdings' U+00A0 is the whole population of
+                    # this case. No transform can invent ink, so regenerating will
+                    # never clear it: counted and printed, but not a failure,
+                    # because a gate that can never go green stops being read.
+                    unexpressible.append(f"{key} U+{int(codepoint):04X}")
+                    continue
+                for axis in range(4):
+                    error = abs(pen.bounds[axis] - want[axis]) / span
+                    if error > worst_ink:
+                        worst_ink = error
+                        worst_ink_where = f"{key} U+{int(codepoint):04X} axis {axis}"
+                    if error > INK_TOLERANCE:
+                        ink_off.append((int(codepoint), axis, error))
+            if ink_off:
+                ink_failures.append(key)
+                detail = ", ".join(f"U+{cp:04X} axis {ax} off {err * 100:.2f}%"
+                                   for cp, ax, err in ink_off[:4])
+                print(f"  ERROR: {key} - {len(ink_off)} ink box edge(s): {detail}")
+
+        off = []
+        for codepoint, want in row.items():
+            glyph = cmap.get(int(codepoint))
+            if glyph is None or want <= 0:
+                continue
+            got = hmtx[glyph][0] / upem
+            error = abs(got - want) / want
+            worst_overall = max(worst_overall, error)
+            if error > TOLERANCE:
+                off.append((int(codepoint), want, got, error))
+        font.close()
+        checked += 1
+
+        if off:
+            # There is no allowance any more. Donors are screened so that every
+            # captured character has its own glyph and can hold its own advance,
+            # so a miss here is a defect rather than a known limitation.
+            failures.append(key)
+            detail = ", ".join(f"U+{cp:04X} want {w:.4f} got {g:.4f}" for cp, w, g, _ in off[:4])
+            print(f"  ERROR: {key} - {len(off)} codepoint(s): {detail}")
+
+    print(f"checked {checked} faces; worst per-character advance error {worst_overall * 100:.3f}%")
+    if ink_capture:
+        print(f"worst ink box edge error {worst_ink * 100:.3f}% ({worst_ink_where})")
+    if unexpressible:
+        print(f"{len(unexpressible)} glyph(s) the Mac paints and the donor cannot: "
+              + ", ".join(unexpressible[:6]))
+    if failures:
+        print(f"FAIL: {len(failures)} face(s) off by more than {TOLERANCE * 100:.1f}%")
+    elif ink_failures:
+        print(f"FAIL: {len(ink_failures)} face(s) with ink box edges off by more "
+              f"than {INK_TOLERANCE * 100:.1f}%")
+    else:
+        print(f"PASS: every advance within {TOLERANCE * 100:.1f}%"
+              + (f" and every ink box edge within {INK_TOLERANCE * 100:.1f}%" if ink_capture else ""))
+    sys.exit(1 if failures or ink_failures else 0)
+
+
+if __name__ == "__main__":
+    main()

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

package/dist/browser-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-controller.d.ts","sourceRoot":"","sources":["../src/browser-controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAc,MAAM,SAAS,CAAC;AAGxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIhE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC,MAAM,CAAC,OAAO,OAAO,oBAAqB,SAAQ,iBAAiB,CAC/D,WAAW,EAAE,6CAA6C;AAC1D,oBAAoB,EAAE,gBAAgB;AACtC,YAAY,EAAE,4BAA4B;AAC1C,EAAE,EAAE,0DAA0D;AAC9D,aAAa,CAChB;IACG,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,SAAS,CAAS;IAEpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BjC;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAiBjC;;;OAGG;YACW,iBAAiB;IAqC/B;;;OAGG;cACa,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCvC;;;OAGG;cACa,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtC;;;OAGG;cACa,QAAQ,CAAC,UAAU,SAAI,GAAG,OAAO,CAAC,aAAa,CAAC;YAqDlD,yBAAyB;IAgOvC;;;OAGG;cACa,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlF;;;OAGG;cACa,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ1D,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI5G"}
+{"version":3,"file":"browser-controller.d.ts","sourceRoot":"","sources":["../src/browser-controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAc,MAAM,SAAS,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAK3F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,OAAO,MAAM,WAAW,CAAC;AAGhC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC,MAAM,CAAC,OAAO,OAAO,oBAAqB,SAAQ,iBAAiB,CAC/D,WAAW,EAAE,6CAA6C;AAC1D,oBAAoB,EAAE,gBAAgB;AACtC,YAAY,EAAE,4BAA4B;AAC1C,EAAE,EAAE,0DAA0D;AAC9D,aAAa,CAChB;IACG,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,WAAW,CAAC,CAAoE;IACxF,OAAO,CAAC,qBAAqB,CAAC,CAAyB;IACvD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IAErD;;;;;;OAMG;IACH,OAAO,KAAK,MAAM,GAEjB;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAsBxB,eAAe;IACf,OAAO,CAAC,eAAe;IAcvB;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAiBjC;;;OAGG;YACW,iBAAiB;IAwC/B;;;OAGG;cACa,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CvC;;;OAGG;cACa,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtC;;;OAGG;cACa,QAAQ,CAAC,UAAU,SAAI,GAAG,OAAO,CAAC,aAAa,CAAC;IAqEhE;;;;;;OAMG;YACW,yBAAyB;IAOvC;;;;;OAKG;YACW,qBAAqB;IAiBnC;;;;OAIG;YACW,oBAAoB;IAUlC;;;OAGG;cACa,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlF;;;OAGG;cACa,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ1D,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI5G"}