Files
archived-camoufox/docs/patch-upgrading-guide.md
T
Jake WriterandClaude Opus 5.5 8599955e0f Update to Firefox 158.0 (#914)
* Pin Firefox 157.0

Camoufox beta.33 is built on Firefox 157.0 (was 156.0.1).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* e2e: expect exactly the identity's input kinds from enumerateDevices()

The probe asserted a non-empty pre-grant device list. Stock Firefox lists one
entry per input kind the machine has and no outputs, so a speaker-only identity
(about 6% of Windows draws) correctly lists nothing. Firefox 157.0's UA bump
re-seeded the Windows preset onto such a machine, and 156.0.1 returns the same
empty list for it.

Compare against the kinds the config claims instead: it still fails on an
empty list for a mic/camera identity, and it now also catches a wrong or
missing kind, a host device leaking through, or an enumerateDevices() error.

Gate-Change: Firefox 157.0's version in the UA re-seeds the Windows preset's media-device draw (pythonlib fingerprints.py from_preset -> identity_seed); verified the same empty list on 156.0.1-beta.32 and 157.0 for the no-mic/no-camera identity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Keep independent window placement with the WM, which Firefox 157 stopped doing

Firefox 157 landed bug 2070008, which deleted the Unix special case in
AppWindow::SizeShell():

    bool positionSet = !mIgnoreXULPosition;
  #if defined(XP_UNIX) && !defined(XP_MACOSX)
    // don't override WM placement on unix for independent, top-level windows
    if (!parentWindow) positionSet = false;
  #endif

so a top-level window now takes the position persisted in the profile's XUL
store instead of leaving placement to the window manager.

That makes window.screenX/screenY a function of leftover profile state, and a
page can read it. Measured on this branch before the fix, same identity, same
Xvfb:

    throwaway profile   screenX 4   screenY 4
    persistent profile  screenX 26  screenY 0

v156.0.1-beta.32 reports 0/0 for both, so the two session types were
indistinguishable and are no longer. fingerprint-injection.patch only answers
GetScreenX/GetScreenY from the config when window.screenX is set, and the
launcher does not draw it for every identity, so the real position shows
through whenever it is absent. A position that varies with profile type
correlates a user's fresh and persistent sessions, and it moves the browser
rect MouseDispatch.js measures (docs/input-dispatch.md).

Nobody places an automation browser's window by hand, so there is no UX here
to gain and determinism to lose. Restores the guard for independent windows
only; dependent windows are still placed relative to their parent, as upstream
intended before and after. Both profile types report 0/0 again.

Caught by typescript/tests/e2e.test.ts:506 in CI, which asserts a persistent
profile presents the same device as a throwaway one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Pin Firefox 157.0.1

Camoufox beta.33 is built on Firefox 157.0.1 (was 157.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Pin Firefox 158.0

Camoufox beta.33 is built on Firefox 158.0 (was 157.0.1).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Port the Playwright bootstrap patch to Firefox 158

Firefox 158 moved the code under six hunks:

- Bug 2072511 replaced HeadlessWidget::mCompositorWidget with a generic
  CompositorWidgetDelegate so the compositor can live in the GPU process.
  The screencast snapshot listener now reaches the in-process
  HeadlessCompositorWidget through AsHeadlessCompositorWidget().
- Bug 2071024 added movementX/movementY to SynthesizeMouseEventData and
  changed the mMovement coalescing check; jugglerEventId and the drag
  event synthesis sit beside the new code.
- Bug 1688932 took bit 25 of nsIWebBrowserChrome's chrome flags for
  CHROME_MEDIA_PIP. JUGGLER_WINDOW_EXPLICIT_SIZE keeps bit 26, the last
  free one.
- Bug 2070965 made UserAgentOverride an nsCString, which moved the
  context of the BrowsingContext field-namespace hunk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Refresh camoufox-window-module.patch context for Firefox 158

Bug 2070772 removed PartnerLinkAttribution.sys.mjs from browser/modules,
so the module list hunk applied only with fuzz. The change is the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Port config.patch to Firefox 158's top-level moz.build

Bug 2070828 appended the SBOM GeneratedFile block to the end of the
top-level moz.build, where config.patch adds the lw directory. The lw
directory is still appended last.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Port the worker userAgent override to Firefox 158's nsCString

Bug 2070965 made WorkerNavigator::GetUserAgent take an nsCString, so the
navigator.userAgent override assigns the UTF-8 config value directly
instead of converting it to UTF-16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Port font-hijacker.patch to Firefox 158's gfx/thebes/moz.build

Bug 2070824 appended license declarations to gfx/thebes/moz.build after
the line the camoucfg include followed. The include is still appended
at the end of the file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Port the network geolocation override to Firefox 158

Bug 2060572 moved the request's logging into the try block and made it
throw first when geo.provider.network.url is unset. The CAMOU_CONFIG
coordinates are now chosen before that check, so a configured location
is reported without depending on the provider URL, as on Firefox 156.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Port the per-context userAgent to Firefox 158's nsACString getters

Bug 2070965 made Navigator::GetUserAgent and WorkerNavigator::GetUserAgent
return UTF-8 and collapsed the window's custom user agent lookup. The
per-context value is still checked first in both getters and is
converted from the UTF-16 it is stored as.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Refresh screen-spoofing.patch context for Firefox 158

nsRFPService::GetSpoofedStorageLimit, next to the declaration the patch
changes, now returns int64_t, so the hunk applied only with fuzz. The
change is the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Refresh sessionstore-popup-close-crash.patch context for Firefox 158

Firefox 158 documented SessionStore.maybeDontRestoreTabs with a JSDoc
block, so the guard applied only with fuzz. The guard is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Port webrtc-ip-spoofing.patch's include to Firefox 158

Bug 2072208 removed NS_PRINTING and the nsIPrintSettings.h include that
followed xpcpublic.h in nsGlobalWindowInner.cpp. WebRTCIPManager.h is
still included after xpcpublic.h.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Qualify webgl-spoofing's dom names in ClientWebGLContext.cpp

ClientWebGLContext.cpp declares no 'using namespace mozilla::dom'. It
compiled on Firefox 157 only because CanvasImageCache.cpp, earlier in the
same unified dom/canvas chunk, did. Bug 2048943 removed that directive
ahead of renaming nsRange to dom::Range, so the patch now names
RoverfoxStorageManager, WorkerPrivate and WebGLParamsManager with their
dom:: namespace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Record Firefox 158.0's content-accessible files and chrome names

The contentaccessible-parity guard compares a build against what stock
Firefox of the same version exposes to pages, and refuses a manifest
recorded from another release. Regenerated with
scripts/gen-contentaccessible-manifest.py from the official 158.0 Linux
x86_64 build (BuildID 20261007201254). Among the changes, Firefox 158 no
longer registers the extra-themes-previews resource host (bug 1990883
removed colorways).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Claim EXT_polygon_offset_clamp where Firefox 158 exposes it

Bug 1854003 added EXT_polygon_offset_clamp to WebGL1 and WebGL2 wherever
the GL backend clamps polygon offsets (GLFeature::polygon_offset_clamp:
GL 4.6, ARB_ or EXT_polygon_offset_clamp). fpgen's records come from
Firefox 146, so no identity claimed it, and stock-gpu-parity found stock
158.0 exposing it on this Linux host where Camoufox did not.

- Windows: ANGLE's D3D11 backend sets polygonOffsetClampEXT from feature
  level 10_0 (renderer11_utils.cpp), which WebGL2 needs, so devices with
  WebGL2 claim it.
- Linux: Mesa (radeonsi, llvmpipe on this host, in GL and GLES contexts)
  and NVIDIA's GL 4.6 driver expose it. Recordings from a desktop GL
  profile, marked by EXT_depth_clamp (96.6% of Linux records), claim it;
  the GLES-only records keep what the device reported.
- macOS: release builds keep webgl.disable-angle and run WebGL on CGL's
  GL 4.1, which lacks it. Metal ANGLE is Nightly-only (bug 2072535).

Both launchers place it in Firefox's alphabetical extension order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Expect EXT_polygon_offset_clamp from the backends Firefox 158 adds it on

The converter and draft-extension tests hard-coded Firefox 156's backend
extensions. The GTX 980 Linux fixture's expected lists now include
EXT_polygon_offset_clamp in Firefox's order, and the Windows device with
WebGL2 expects it beside EXT_depth_clamp; every other assertion is
unchanged. A new test derives the expectation for 100 draws per OS from
each draw itself: Windows devices with WebGL2, Linux desktop GL
recordings, never macOS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gate-Change: Firefox 158 (bug 1854003) exposes EXT_polygon_offset_clamp where GLFeature::polygon_offset_clamp holds, and ANGLE D3D11 sets it from feature level 10_0; verified in the 158.0 source (dom/canvas/WebGLExtensions.cpp, gfx/gl/GLContextFeatures.cpp, third_party/angle renderer11_utils.cpp) and by stock-gpu-parity against stock 158.0 on this host

* Follow Firefox 158's WebSocket frame callbacks in Juggler

Bug 1719394 added the HTTP channel ID to
nsIWebSocketEventListener.frameReceived and frameSent, ahead of the
frame. Juggler's listener still took (serialID, frame), so it read the
channel ID as the frame, found no opCode and dropped every frame:
Playwright's framereceived and framesent events never fired
(test_websocket.py::test_should_emit_frame_events and
test_should_reject_wait_for_event_on_close_and_error failed on 158 and
pass on 156.0.1). The listener now takes the new argument.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Key Juggler's pending promises by their Debugger.Object

Bug 2044184 removed Debugger.Object.promiseID in Firefox 158. Juggler
keyed the promises it awaits by it, so every pending promise shared the
key undefined: a second awaited evaluate overwrote the first, which then
never resolved. Playwright waits that poll in the page (waitForElementState,
selectText waiting for visibility) hung whenever another evaluate
returning a promise ran meanwhile. The Debugger.Object is unique per
promise within the debugger and serves as the key instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Keep the environment out of forked children's command lines

Firefox's setproctitle() marks the end of the old argv space so the
kernel shows only the new title, then copies the environment strings
right after the title, inside that space. When an environment string's
null lands on the marker, the kernel shows the whole space: the title
followed by the environment. Whether it does depends only on the length
of the install path and of the environment, so it is rare in stock
Firefox. The Firefox 158 package at the parity harness's path hit it on
the RDD process, whose /proc/PID/cmdline then ended in the launching
shell's environment instead of 'rdd'. The marker is set again after the
copy; it lies outside /proc/PID/environ, which is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 17:08:56 +00:00

17 KiB

Firefox Patch Upgrading Guide

How to update Camoufox's patches when browser/upstream.sh moves to a new Firefox version. Patches break because Firefox renames APIs, moves code and shifts line numbers; this guide covers finding and fixing those rejects.

Table of Contents

  1. Understanding the Patch System
  2. The Source Tree and Its Make Targets
  3. General Workflow
  4. Fixing Common Reject Types
  5. Per-Context Machinery
  6. Porting Playwright
  7. Testing and Validation
  8. Pitfalls

Understanding the Patch System

Patch Categories

All patches live under browser/patches/, and browser/scripts/patch.py applies every *.patch in it (subdirectories included), sorted by file name:

  • Playwright: playwright/0-playwright.patch (Juggler integration) and playwright/1-leak-fixes.patch. Their names sort first, and every other patch is written against a tree that already has them.
  • Feature patches: webrtc-ip-spoofing.patch, anti-font-fingerprinting.patch, etc. Per-user-context (per-Playwright-context) support is built into each one.
  • librewolf/, ghostery/: patches taken from those projects.

Compile-time dependencies between patches (MaskConfig, RoverfoxStorageManager) are listed in browser/patches/patch-dependencies.md.

Key Infrastructure Files

  • RoverfoxStorageManager.cpp/h: Thread-safe key-value storage for per-context data
  • Manager Classes: AudioFingerprintManager, WebRTCIPManager, etc.
  • Window.webidl: Exposes the per-context setters to Playwright

The Source Tree and Its Make Targets

The Firefox tree is browser/camoufox-<version>-<release>/ (from browser/upstream.sh). It is a git repository whose unpatched tag is plain Firefox plus browser/additions/ and browser/settings/. Run every target, and every command in this guide that does not say otherwise, from browser/:

Target What it does
make dir Fetches and extracts Firefox if the tree is missing. Otherwise resets it to unpatched, runs mach clobber and git clean -fdx (the object directory goes too), re-copies additions, then applies every patch and lists the ones that left rejects.
make revert git reset --hard unpatched. Untracked files stay, including new files that patches created.
make clean mach clobber, git clean -fdx, then make revert: unpatched Firefox with nothing left over, without re-fetching.
make patch ./patches/x.patch Applies one patch (patch -p1).
make unpatch ./patches/x.patch Reverses one patch.
make first-checkpoint Commits the current tree and tags it first-checkpoint.
make workspace ./patches/x.patch Unapplies x if it is applied, runs first-checkpoint, then applies x again, so the working tree differs from the checkpoint by exactly that patch.
make diff git diff first-checkpoint. Redirect it into the patch file.
make checkpoint Commits tracked changes, keeping the first-checkpoint tag where it is.
make grep <text> Searches the top-level patches for a string.
make build ./mach build (runs make dir first if the tree was never prepared).
make run Runs the build with debug on in CAMOU_CONFIG; wipes ~/.camoufox. args="..." passes arguments.
make path Prints the built camoufox-bin.
make stage-fonts Stages the font bundle into the unpackaged build, which tests through the launchers need.
make tests The Playwright suite against the build (headful=true for headed).
make help Lists every target.

git diff does not show untracked files. Before make diff, mark new files with git add -N <file> inside the source tree, or they will be missing from the patch.


General Workflow

Step 1: Bump the Version and Find the Broken Patches

Update version and release in browser/upstream.sh, then:

make dir

patch.py applies every patch and ends with a list of the ones that failed and their reject files. It deletes the .rej files after listing them, so reproduce each failure one patch at a time (Step 2).

Step 2: Set Up One Patch

Start from a clean unpatched tree, apply what the patch builds on (at least the Playwright patches, plus anything from browser/patches/patch-dependencies.md), checkpoint, then apply the broken patch. Use make clean rather than make revert here: files that other patches created survive a revert and make patch stop on "previously applied" prompts.

make clean
make patch ./patches/playwright/0-playwright.patch
make patch ./patches/playwright/1-leak-fixes.patch
make first-checkpoint
make patch ./patches/patch-name.patch     # fails, leaving .rej files

Find the reject files:

cd camoufox-<version>-<release>
find . -name '*.rej' -type f

Step 3: Analyze Each Reject File

Read the reject file to understand what failed:

cat path/to/file.cpp.rej

Reject files show:

  • @@ lines: Line numbers where patch expected to apply
  • - lines: What the patch expected to find (old code)
  • + lines: What the patch wanted to add (new code)

Step 4: Locate the Correct Position in Firefox Code

The line numbers in rejects are usually wrong for the new Firefox version. You need to:

  1. Search for unique context around the reject
  2. Understand what the patch is doing
  3. Find equivalent location in new Firefox code

Step 5: Apply Changes Manually

Edit the file to make the rejected change at the correct location.

Step 6: Remove Reject Files

After fixing all rejects, delete the .rej files and any .orig backups patch left, so they do not end up in the diff:

find . -name '*.rej' -o -name '*.orig' | xargs rm -f

Step 7: Write the Updated Patch

From browser/:

(cd camoufox-<version>-<release> && git add -N path/to/new/file.cpp)   # new files only
make diff > patches/patch-name.patch

Step 8: Verify

Run make dir again. The patch should no longer be listed as failing.


Fixing Common Reject Types

Type 1: Include Directive Rejects

Symptom: Reject shows failed #include additions

Example Reject:

@@ -325,6 +325,7 @@
 #include "xpcpublic.h"

+#include "WebRTCIPManager.h"
 #include "nsDocShell.h"

How to Fix:

  1. Read the actual file to find the includes section
  2. Search for nearby includes (e.g., xpcpublic.h)
  3. Add the new include in the appropriate location
  4. Firefox include order: system headers, then Mozilla headers, alphabetically within groups

Example:

// Find this in the actual file:
#include "xpcpublic.h"

// Add the missing includes after it:
#include "xpcpublic.h"

#include "WebRTCIPManager.h"
#include "nsDocShell.h"
#include "mozilla/OriginAttributes.h"

Type 2: Function Signature Changes

Symptom: Reject shows function call with changed parameters

Example Reject:

-  mouseOrPointerEvent.mButton = aButton;
+  mouseOrPointerEvent.mJugglerEventId = aMouseEventData.mJugglerEventId;

Common Causes:

  • Firefox refactored the API
  • Parameters moved from individual args to struct/data object
  • Parameter order changed

How to Fix:

  1. Search for the function definition in Firefox source
  2. Understand the new API structure
  3. Port the patch logic to the new API

Example - Firefox 146 Mouse Event Refactoring:

Old Firefox 144 API (individual parameters):

void SynthesizeMouseEvent(int x, int y, int button, ...)

New Firefox 146 API (structured data):

void SynthesizeMouseEvent(SynthesizeMouseEventData& aData,
                         SynthesizeMouseEventOptions& aOptions)

Port the patch:

// Old patch code:
mouseEvent.mButton = aButton;
mouseEvent.jugglerEventId = aJugglerEventId;

// New patch code for Firefox 146:
mouseOrPointerEvent.mButton = aMouseEventData.mButton;
mouseOrPointerEvent.mJugglerEventId = aMouseEventData.mJugglerEventId;
mouseOrPointerEvent.convertToPointer = aOptions.mConvertToPointer;

Type 3: Missing Context - Code Moved

Symptom: Reject shows context that doesn't exist in the file

How to Fix:

  1. Use grep to search for unique function names or variables in the reject
  2. Find where Firefox moved the code
  3. Apply the patch to the new location
# Search across the codebase
grep -r "FunctionName" camoufox-<version>/ --include="*.cpp"

Type 4: New Parameter Added to Function Calls

Symptom: Reject shows function call, but Firefox added/removed parameters

Example - MakeTextRun userContextId:

Old call:

MakeTextRun(text, len, drawTarget, appUnitsPerDevPixel, flags, recorder);

New Firefox expects:

MakeTextRun(text, len, drawTarget, appUnitsPerDevPixel, flags, recorder, userContextId);

How to Fix:

  1. Extract userContextId from available context (Document, PresContext, etc.)
  2. Add proper extraction code before the call
  3. Pass userContextId as the last parameter

userContextId extraction: the per-context patches resolve it from the BrowsingContext, which exists before the document's attributes are set:

uint32_t userContextId = 0;
if (BrowsingContext* bc = win->GetBrowsingContext()) {
  userContextId = bc->OriginAttributesRef().mUserContextId;
}
MakeTextRun(..., userContextId);

Workers use WorkerPrivate::GetOriginAttributes() instead.

Type 5: Line Number Shifts (No Code Changes)

Symptom: Reject shows patch tried to apply at wrong line number, but code is identical

How to Fix:

Simply apply the patch manually at the correct line number. The code hasn't changed, just the location.


Per-Context Machinery

Most spoofing patches carry per-context support. When porting one, expect these pieces:

  1. Manager classes (e.g., AudioFingerprintManager, WebRTCIPManager):

    • Store per-context settings using RoverfoxStorageManager
    • Gate their setter with RoverfoxStorageManager::IsSetterOffered and MarkSetterUsed
  2. Window.webidl functions:

    • JavaScript APIs exposed to Playwright
    • Examples: setAudioFingerprintSeed(), setWebRTCIPv4()
  3. nsGlobalWindowInner.cpp implementations:

    • Extract userContextId from window/document/docshell
    • Call manager classes
    • Remove the setter after use with RoverfoxStorageManager::RemoveSetter
  4. Core logic changes:

    • Consult the per-context manager before the global config (MaskConfig)
    • Pass userContextId through call chains

See per-context-patches.md for the full list.


Porting Playwright

The two Playwright patches (browser/patches/playwright/) and Camoufox's Juggler (browser/additions/juggler/) both started from upstream Playwright and both carry Camoufox changes: fixes to Juggler's input and navigation paths, the isolated-world page agent, and the human cursor (input/). Port upstream changes into them; never copy upstream over them.

The Bootstrap Patch

Compare what changed in Playwright's bootstrap.diff since the last sync, then port it like any other patch:

make dir
make workspace ./patches/playwright/0-playwright.patch
# port the upstream changes into camoufox-<version>-<release>/
make diff > patches/playwright/0-playwright.patch

Juggler

git clone https://github.com/microsoft/playwright.git /tmp/playwright
diff -r additions/juggler/ /tmp/playwright/browser_patches/firefox/juggler/

Port the upstream hunks one by one, keeping the Camoufox changes. Then check:

  1. components/Juggler.js still exports JugglerFactory.

  2. components/components.conf registers it with esModule (Firefox no longer supports jsm) and "constructor": "JugglerFactory":

    {
        "esModule": "resource://gre/modules/juggler/components/Juggler.js",
        "constructor": "JugglerFactory",
    }
    
  3. Every file upstream added or renamed is listed in FINAL_TARGET_FILES in juggler/moz.build, and every ChromeUtils.importESModule() path still exists. Upstream registers a juggler chrome package in jar.mn; Camoufox does not, because a page can detect one (see juggler/moz.build), so upstream's chrome://juggler/content/ paths become resource://gre/modules/juggler/.

Then make dir && make build && make tests. A wrong components.conf shows up as one of these:

Error Cause
undefined symbol: ... mozCreateComponent<nsICommandLineHandler>() at link time components.conf is not an ESM component
Externally-constructed components may not specify 'constructor' or 'legacy_constructor' properties It uses jsm instead of esModule
Externally-constructed components must specify a type other than nsISupports It is an external component with no type; make it an ESM component
JavaScript components must specify a constructor The constructor field is missing

Testing and Validation

Minimal Verification

After updating a patch, always verify:

  1. Every patch applies cleanly: make dir lists no failures.

  2. Build compiles (if feasible):

    make build
    

Full Testing

Run the suites that cover the patch (see ci/README.md). From the repository root, python3 -m ci.run_patch_guards --binary <camoufox-bin> is the most direct evidence that a patch which still applies was not neutered by the upgrade.

Browser-Owned GPU Values

The launchers build WebGL from fpgen's recordings, which an older Firefox made. Some values are the browser's rather than the GPU's, and an upgrade can change them on every device: Firefox 156 added EXT_depth_clamp on Windows and fixed WebGL1's ALIASED_LINE_WIDTH_RANGE at [1, 1] on Linux (webgl-browser-owned-values-follow-firefox). Firefox 158 added EXT_polygon_offset_clamp on Windows devices with WebGL2 (ANGLE's D3D11 backend at feature level 10_0 and above) and on Linux desktop GL, but not on macOS, where release builds use CGL's GL 4.1. The stock-gpu-parity guard finds them. It runs stock Firefox of the new version, stock Firefox of the release fpgen's model recorded, and Camoufox claiming the machine's GPU, and fails where the two stock releases differ and Camoufox does not follow the new one. From the repository root:

python3 -m ci.run_patch_guards --binary <camoufox-bin> --only stock-gpu-parity

CI runs it on Linux with a software renderer. Run it on Windows and macOS too, passing the stock binaries by hand, because each OS has its own graphics backend. From the repository root:

python3 browser/tests/playwright/patches/stock-gpu-parity.py --binary <camoufox-bin> \
    --stock <Firefox of upstream.sh's version> --recorded-stock <Firefox of fpgen's release>

For each failure, find in the Firefox source why the value changed and whether it holds on every device of that backend, then follow it where the launchers convert a recording (to_config in python/src/camoufox/webgl.py and typescript/src/webgl.ts).


Pitfalls

Pitfall Avoid it by
Trusting reject line numbers Searching for the context lines instead
Hand-editing a .patch file Editing the tree and running make diff
Missing new files in the patch git add -N them before make diff
A diff that includes the patch's dependencies Running make first-checkpoint after applying them and before the patch being fixed
.rej and .orig files in the diff Deleting them first (Step 6)
Guessing a value a refactored API now needs Reading the new Firefox code, or the release notes
Fixing several patches in one pass One patch at a time, each from make clean

Appendix: Firefox Source Navigation

Finding Files

# Find files by name
find . -name "Navigator.cpp" -type f

# Find files containing a symbol
grep -r "GetAcceptLanguages" . --include="*.cpp"

# Find class definitions
grep -r "class Navigator" . --include="*.h"

Understanding Firefox Code Structure

  • dom/: DOM implementation
    • dom/base/: Core DOM classes (Window, Document, Navigator, etc.)
    • dom/webidl/: WebIDL interface definitions
    • dom/media/webrtc/: WebRTC implementation
  • gfx/: Graphics and font rendering
    • gfx/thebes/: Text rendering (fonts, glyphs, shaping)
  • layout/: Layout engine
    • layout/generic/: Text frames
    • layout/mathml/: MathML rendering

Checklist

  • Bump browser/upstream.sh and run make dir to list the failing patches
  • For each: make clean, apply its dependencies, make first-checkpoint, make patch it
  • Port each reject to the new Firefox code
  • Remove .rej and .orig files, git add -N new files
  • make diff > patches/<name>.patch
  • make dir applies the whole stack cleanly, with no fuzz
  • make build, then run the patch guards; firefox-version-pin checks that the build and every identity are the new Firefox
  • Run stock-gpu-parity on Linux, Windows and macOS (Browser-Owned GPU Values)

Additional Resources