{"owner":"chromiumembedded","repo":"cef","hasSkills":true,"totalSkillsCount":10,"totalTokensCount":18549,"categories":["project-spec","root-instruction","claude-rule","plugin-manifest","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":["docs/architecture.md","tools/AGENTS.md","tools/CLAUDE.md","tools/cefbuilds/README.md","tools/clang/CLAUDE.md","tools/clang/README.md","tools/clang/standalone/README.md","tools/claude/README.md","tools/debug/ax_viewport_collapse/README.md","tools/gpt/README.md"],"skills":{"docs/architecture.md":"This page provides an overview of the CEF architecture.\n\n**Contents**\n\n- [Overview](#overview)\n- [Dependencies](#dependencies)\n- [Versions](#versions)\n- [History](#history)\n- [Modern Architecture](#modern-architecture)\n- [Common API Usage](#common-api-usage)\n- [C Wrapper API](#c-wrapper-api)\n- [CEF1 (Discontinued)](#cef1-discontinued)\n  - [API Usage](#api-usage)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n- [CEF2 (Discontinued)](#cef2-discontinued)\n- [CEF3](#cef3)\n  - [API Usage](#api-usage)\n  - [Process Considerations](#process-considerations)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n    - [Alloy Runtime Classes](#alloy-runtime-classes)\n    - [Chrome Runtime Classes](#chrome-runtime-classes)\n\n---\n\n# Overview\n\nThe Chromium Embedded Framework (CEF) is an open source project founded by Marshall Greenblatt in 2008 to develop a Web browser control based on the [Google Chromium](http://www.chromium.org/Home) project. CEF currently supports a range of programming languages and operating systems and can be easily integrated into both new and existing applications. It was designed from the ground up with both performance and ease of use in mind. The base framework includes C and C++ programming interfaces exposed via native libraries that insulate the host application from Chromium and Blink implementation details. It provides close integration between the browser control and the host application, which can optionally control resource loading, navigation, context menus, printing, JavaScript bindings and more, while taking advantage of the same performance and HTML5 technologies available in the Google Chrome Web browser.\n\nSee the project [README.md](https://github.com/chromiumembedded/cef/blob/master/README.md) for additional introductory material.\n\n# Dependencies\n\nThe CEF project depends on a number of other projects maintained by third parties. The major projects that CEF depends on are:\n\n  * [Chromium](http://www.chromium.org/Home) - Provides general functionality like network stack, threading, message loop, logging and process control needed to create a fully functional Web browser. Implements \"platform\" code that allows Blink to communicate with V8 and Skia. Many Chromium design documents can be found at http://dev.chromium.org/developers.\n  * [Blink](https://www.chromium.org/blink) (formerly WebKit) - The rendering implementation used by Chromium. Provides DOM parsing, layout, event handling, rendering and HTML5 JavaScript APIs. Some HTML5 implementations are split between the Blink and Chromium code bases.\n  * [V8](https://developers.google.com/v8/) - JavaScript engine.\n  * [Skia](https://skia.org/) - 2D graphics library used for rendering non-accelerated content. More information on how Chromium integrates Skia is available [here](http://www.chromium.org/developers/design-documents/graphics-and-skia).\n  * [Angle](https://chromium.googlesource.com/angle/angle/+/master/README.md) - 3D graphics translation layer for Windows that converts GLES calls to DirectX. More information about accelerated compositing is available [here](http://dev.chromium.org/developers/design-documents/gpu-accelerated-compositing-in-chrome).\n\n# Versions\n\nThere have been three versions of CEF to date.\n\n  * CEF1 - Single process implementation using the Chromium WebKit API (now discontinued).\n  * CEF2 - Multi process implementation built on the Chromium browser (now discontinued).\n  * CEF3 - Multi process implementation using either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\").\n\nOnly the CEF3 version is currently developed and supported. See the \"History\" and \"Modern Architecture\" sections below for background and the [Branches And Building](branches_and_building.md) page for current development information.\n\n# History\n\nIn 2008, when the CEF project started, Chromium was a monolithic application built on top of Apple's [WebKit](https://webkit.org/) rendering engine. Google maintained an in-tree variant of WebKit (called the [Chromium WebKit API](https://www.youtube.com/watch?v=JFzC_Gx76E8)) that added additional functionality specific to Chromium. The first version of CEF (called CEF1) was implemented on top of this Chromium WebKit API and used the default single-process application model supported by WebKit1 at that time (for more details on CEF1 architecture see the \"CEF1\" section below).\n\nUse of the Chromium WebKit API came with some known limitations. For example, that API layer did not support the multi-process model that was the basis for most of Google Chrome's [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md). It also lacked many of the UI features that were becoming necessary to support new web platform features (like device selection dialogs, permissions management, etc). We therefore began a new effort, in 2010, to reimplement CEF (called CEF2) on top of the fully-featured but monolithic Chromium browser UI. The lack of internal API boundaries in the Chromium code at that time made it necessary for us to take an \"all or nothing\" approach. If we could create a CEF browser window based on the complete Chrome UI we would effectively gain access to all of Chrome's capabilities \"for free\" (for more details on CEF2 architecture see the \"CEF2\" section below).\n\nGoogle began acknowledging the validity of the embedded use case for Chromium in 2010 and started work on new internal API boundaries to make embedding easier. The [Chromium Content API](http://www.chromium.org/developers/content-module/content-api), which encapsulated the multi-process application model and provided stub implementations for most web platform features, reached a development stage in late 2011 where it was a viable option for Chromium embedders like CEF. It still didn't provide all of the features that we might like, but it was a \"supported\" API layer. We therefore abandoned the CEF2 effort in early 2012 and focused our efforts instead on the Content API as the more viable embedding option. The existing CEF1 API, which was strongly dependent on WebKit1 and the single-process model, could not be directly ported to the Content API. A new CEF API (called CEF3), with substantial breaking API changes and multi-process support, was released in early 2013 (for more details on CEF3 architecture see the \"Modern Architecture\" and \"CEF3\" sections below).\n\nAlso in 2013, Google decided to [fork the WebKit project](https://blog.chromium.org/2013/04/blink-rendering-engine-for-chromium.html). After renaming it to Blink they removed many of the API boundaries that had previously existed between Chromium and WebKit and effectively deleted the Chromium WebKit API. The multi-process architecture, which was optional in WebKit1, was now a requirement with Chromium/Blink. CEF1, which depended on the Chromium WebKit API, no longer had a viable future and CEF3 became the only path forward.\n\nFast forward another 7 years, to 2020, and the Chromium architecture has again changed substantially. A lot of effort has been spent to define clear architectural layers (sometimes called [components](https://www.chromium.org/developers/design-documents/cookbook/)) in the Chromium/Blink source code. New platforms and new embedders have entered the Chromium ecosystem. And yet, many features desired by CEF users remain stubbornly out of reach in the Chrome UI layer. With this new, more modern, version of Chromium, we decided it was time to revisit our goals from CEF2 and create a new CEF version based on the Chrome UI layer (now called the \"Chrome runtime\" in CEF3). Continue to the \"Modern Architecture\" section for details.\n\n# Modern Architecture\n\nThe modern Chromium code base is composed of architectural layers, with the primary application layers being \"content\" (for the [Content API](http://www.chromium.org/developers/content-module/content-api)) and \"chrome\" (for the Chrome UI layer). The \"content\" layer includes [WebContents](https://source.chromium.org/chromium/chromium/src/+/master:content/public/browser/web_contents.h) as the primary browser object and provides implementations for most of the generic web platform and application/process management functionality. The \"chrome\" layer includes [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) as the primary browser object and provides implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc.\n\nFor historical reasons (outlined above), CEF browser windows have been based on the \"content\" layer WebContents object since the introduction of CEF3 in 2013. Adding support for additional \"chrome\" layer features in that architecture was a serious effort because it involved careful understanding and cherry-picking of the related functionality from \"chrome\" code into the CEF code base. Over time we have added dependencies on the \"chrome\" layer targets to support some features in CEF (such and extensions, PDF viewer and print preview) and to avoid code duplication. As a result, CEF3 binaries in modern times already contained most/all of the code that would be required to launch a stand-alone \"chrome\" Browser window, but simply lacked the mechanism to do so.\n\nIn 2020 we launched a [new effort](https://github.com/chromiumembedded/cef/issues/2969) to implement the CEF3 API on top of a fully-featured \"chrome\" Browser window. To be usable in existing CEF3 client applications the \"chrome\" window needed to support a large subset of CEF3's existing callbacks/intercepts (e.g. loading progress, network requests, etc.), and be inserted into the existing [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) structure. At the same time, it was necessary to substantially refactor the internal CEF (libcef) code to extract functionality that was common to both the old WebContents-based approach and the new Browser-based approach. As part of this refactoring we renamed the existing \"content\" layer implementation to the \"Alloy runtime\" (where Alloy = Chrome + other stuff) and named the new \"chrome\" layer implementation as the \"Chrome runtime\". Proceed to the \"CEF3\" section below for additional feature and implementation details.\n\n# Common API Usage\n\nAll versions of CEF expose a simple, easy-to-use API designed to insulate users from the underlying Chromium and Blink code complexity. Common usage is as follows:\n\n1. Initialize CEF by calling CefInitialize().\n\n2. Perform work on the UI message loop by calling CefRunMessageLoop() or CefDoMessageLoopWork().\n\n3. Create a browser window by calling CreateBrowser() or CreateBrowserSync() and passing in a CefClient instance.\n\n4. Shut down CEF by calling CefShutdown() before the application exits.\n\n# C Wrapper API\n\nThe libcef shared library exports a C API that isolates the user from the CEF runtime and code base. The libcef\\_dll\\_wrapper project, which is distributed in source code form as part of the binary release, wraps this exported C API in a C++ API that is then linked into the client application. The code for this C/C++ API translation layer is automatically generated by the [translator](https://github.com/chromiumembedded/cef/blob/master/tools/translator.README.txt) tool. Direct usage of the C API is described on the [Using The CAPI](using_the_capi.md) page.\n\n# CEF1 (Discontinued)\n\nCEF1 was the initial version of CEF first released in 2008. It was discontinued in 2013 when Google forked the WebKit project and subsequently deleted the Chromium WebKit API. See the \"History\" section above for additional details.\n\nThe single process architecture used by CEF1 integrates Chromium and WebKit directly into the client application. Advantages to the single process architecture included reduced memory usage and closer integration with the client application. For example, having the renderer running in the same process allowed JavaScript bindings to synchronously communicate between client code and renderer code. Disadvantages included [reduced performance](https://github.com/chromiumembedded/cef/issues/304) with certain types of accelerated content, [crashes](https://github.com/chromiumembedded/cef/issues/242) due to plugins like Flash running in the same process, and lack of support for application [security and stability features](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md) that required a multi-process architecture.\n\n## API Usage\n\nBelow is an overview of the main CEF1 interfaces and their uses. Since CEF1 is discontinued we no longer provide detailed usage information.\n\n  * [CefApp](http://magpcss.org/ceforum/apidocs/projects/(default)/CefApp.html) - This interface is passed to CefInitialize() and allows the application to customize global functionality like resource loading and proxy handling.\n  * [CefClient](http://magpcss.org/ceforum/apidocs/projects/(default)/CefClient.html) - This interface is passed to CefCreateBrowser() or CefCreateBrowserSync() and acts as the connection between an individual CEF browser instance and the client application. Additional interfaces for request handling, display handling, etc. are exposed via this interface.\n  * [CefBrowser](http://magpcss.org/ceforum/apidocs/projects/(default)/CefBrowser.html) - Exposes capabilities provided by the browser. This includes back/forward navigation, source retrieval, request loading, etc. A single CefBrowser may have one or more child [CefFrame](http://magpcss.org/ceforum/apidocs/projects/(default)/CefFrame.html) objects.\n\n## Threading Considerations\n\nCEF1 includes UI, IO and FILE threads. The UI thread creates browser windows and is used for all interaction with WebKit and V8. The IO thread is used for handling schema and network requests. The FILE thread is used for the application cache and other miscellaneous activities.\n\nWhen using CEF1 you should keep the following threading considerations in mind:\n\n  * Do not perform blocking operations on the UI thread. This can lead to serious performance issues.\n  * The UI thread will be the same as the main application thread if CefInitialize() is called with a CefSettings.multi\\_threaded\\_message\\_loop value of false.\n  * All WebKit and V8 interation must take place on the UI thread. Consequently, some CEF API functions can only be called on the UI thread. Functions that have this limitation will be documented accordingly in the associated CEF header file.\n  * The [CefPostTask](http://magpcss.org/ceforum/apidocs/projects/(default)/(_globals).html#CefPostTask(CefThreadId,CefRefPtr<CefTask>)) method can be used to post tasks asnychronously between the various threads.\n\n## Implementation Details\n\nCEF1 has the following major implementation classes:\n\n  * CefContext - Represents the global CEF context. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * CefProcess - Used by CefContext to create and manage the CEF threads.\n  * BrowserWebKitInit - Manages the global WebKit environment as exposed by the Chromium WebKit API.\n  * WebViewHost - Provides the native window \"wrapper\" implementation for a WebView. This class extends WebWidgetHost which provides functionality shared in common with popup widgets (like select menus) on some platforms.\n  * CefBrowserImpl - Implements the CefBrowser interface, creates the WebViewHost and provides the glue code for a single browser instance.\n  * BrowserWebViewDelegate - Implements the WebKit interfaces that provide communication between CefBrowserImpl and the underlying WebView.\n\n# CEF2 (Discontinued)\n\nCEF2 was an effort to reimplement the CEF1 API on top of the Chrome browser UI as it existed in 2010. CEF2 was discontinued when Chromium announced support for the Content API. Information about CEF2 can be found in the \"History\" section above and [here](http://magpcss.org/ceforum/viewtopic.php?f=10&t=122) on the CEF Forum.\n\n# CEF3\n\nCEF3 has been the recommended and supported version of CEF since January 2013. It uses the same multi process architecture as the Chromium Web browser via either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\"). This architecture provides a number of advantages over the single process architecture used by CEF1:\n\n  * Support for multi-process run mode (with related [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md)).\n  * More code sharing with the Chromium browser.\n  * Improved performance and less breakage due to use of the \"supported\" code path.\n  * Faster access to new features.\n\nIn most cases CEF3 will have the same performance and stability characteristics as the Chromium Web browser. Both the Alloy runtime and the Chrome runtime support modern web platform features and provide the safety/security expected from an up-to-date Chromium-based browser. The Chrome runtime, which was introduced in 2020, adds implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc. At the time of writing, the Chrome runtime requires use of the [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) in CEF client applications and does not support off-screen rendering. A current list of open issues specific to the Chrome runtime can be found [here](https://github.com/chromiumembedded/cef/issues?q=is%3Aissue+is%3Aopen+label%3Achrome).\n\nStarting with the M125 release (mid-2024) the Alloy runtime has been [split](https://github.com/chromiumembedded/cef/issues/3681) into separate style and bootstrap components. Both Chrome style and Alloy style browsers/windows can now be created while using the Chrome bootstrap. The Alloy bootstrap has been [removed](https://github.com/chromiumembedded/cef/issues/3685) starting with the M128 release.\n\n## API Usage\n\nSee the [General Usage](general_usage.md) page for detailed API usage instructions.\n\n## Process Considerations\n\nSee the [Processes](general_usage.md#processes) section of the [General Usage](general_usage.md) page for details.\n\n## Threading Considerations\n\nSee the [Threads](general_usage.md#threads) section of the [General Usage](general_usage.md) page for details.\n\n## Implementation Details\n\nFor an implementation overview see the \"Modern Architecture\" section above. \n\nShared CEF library/runtime classes use the Cef prefix. Classes that implement the Alloy or Chrome runtime use the Alloy or Chrome prefixes respectively. Classes that extend an existing Chrome-prefixed class add the Cef or Alloy suffix, thereby following the existing naming pattern of Chrome-derived classes.\n\n### Alloy Runtime Classes\n\nAlloy runtime bootstrap was [removed](https://github.com/chromiumembedded/cef/issues/3685) in M128 (mid-2024) and Alloy runtime style is now supported using the Chrome runtime bootstrap. Alloy runtime style is based on the \"content\" layer and has the following major implementation classes:\n\n  * [AlloyBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/alloy/alloy_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n\n### Chrome Runtime Classes\n\nChrome runtime bootstrap and style is based on the \"chrome\" layer and has the following major implementation classes:\n\n  * [ChromeMainDelegateCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_main_delegate_cef.h) - Implements the common process bootstrap logic.\n  * [ChromeContentClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_content_client_cef.h) - Implements the Content API callbacks that are common to all processes.\n  * [CefContext](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/context.h) - Represents the global CEF context in the browser process. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * [ChromeBrowserMainExtraPartsCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_main_extra_parts_cef.h) - Implements the browser process bootstrap logic.\n  * [ChromeContentBrowserClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_content_browser_client_cef.h) - Implements the Content API callbacks for the browser process.\n  * [ChromeBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n  * [ChromeContentRendererClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/chrome/chrome_content_renderer_client_cef.h) - Implements the Content API callbacks for the render process.\n  * [CefBrowserImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/browser_impl.h) - Implements the CefBrowser interface in the render process. Provides the glue code and implements interfaces for communicating with the RenderView.\n  * [ChromeBrowserDelegate](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_delegate.h) - Interface injected into Chrome's [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) object (via [patch files](https://github.com/chromiumembedded/cef/blob/master/patch/README.txt)) to support callbacks into CEF code.\n  * [ChromeBrowserFrame](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h) - Widget for a Views-hosted Chrome browser.\n\nAn overview of the Chrome Browser object model is also available [here](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h).","tools/AGENTS.md":"# CEF Tools Contributor and Agent Guidelines\n\nThis file applies to `//cef/tools` and its descendants.\n\n## Generator inventory and coverage\n\n- Every direct-child, non-test `make_*.py` generator must have a matching\n  `make_*_test.py` module.\n- `make_generator_inventory_test.py` enforces the direct-child inventory. When\n  adding or removing a generator, update its expected count intentionally and\n  keep nested generators, helpers, and existing tests out of the inventory.\n- Exercise every top-level generator function through at least one successful\n  test. Cover meaningful explicit error branches, writer behavior, and the\n  generator's CLI style; do not treat filename coverage as function coverage.\n- Use standard-library `unittest`, `tempfile`, and `unittest.mock`. Run from the\n  CEF root:\n\n  ```sh\n  python3 -m unittest discover -s tools -p '*_test.py'\n  python3 -m unittest discover -s tools -p 'make_example_test.py' -v\n  ```\n\n- Run the complete suite twice for generator-wide work. These modules share\n  parser state, so the second run detects ordering and cleanup leaks.\n\n## Hermetic fixtures and goldens\n\n- Put deterministic inputs and reviewed goldens under\n  `tools/testdata/make_generators/`; use `generator_test_util.py` for shared\n  fixture, manifest, archive, and CLI helpers.\n- Mock or fix time, year, Git metadata, versions, platforms, environment\n  variables, external commands, and formatter results when they affect output.\n- Goldens must originate from a reviewed baseline, never from ignored\n  working-tree output, and tests must not contain an auto-update path.\n- Use inline expectations for small output and reviewed full-file goldens for\n  larger generated C/C++ content. Add targeted assertions that explain the\n  behavior protected by a golden.\n- Prove that customized CppToC/CToCpp bodies survive regeneration, source\n  fixtures are not modified, and relevant paths work when they contain spaces.\n\n## Writer contracts\n\n- Test every writer on its first generation and an identical second\n  generation.\n- For `write_file_if_changed`, assert changed/unchanged returns and preserved\n  mtime. For unconditional writers, assert stable bytes across rewrites.\n- Multi-output writers must report a change when any output changes. Test\n  repairs where only one output was corrupted.\n- Pre-publication failures must leave outputs missing or unchanged. Characterize\n  partial I/O-failure output before changing it; atomic publication is a\n  separate behavior change.\n\n## CLI contracts\n\n- Cover invalid status, stdout, stderr, and partial artifacts, plus successful\n  stdout, single-file, multi-output, argparse, and distribution CLI styles.\n- If a generator function returns metadata with its content, such as\n  `(content, customized)`, unpack the result at the CLI boundary and write only\n  the string content. Do not change the underlying generator return contract\n  merely to fix a CLI.\n- Assert progress messages exactly when callers may depend on them, and return\n  explicit nonzero statuses for rejected invocations.\n\n## Parser and module state\n\n- Restore parser notification context and other module globals with\n  `try/finally`; add test cleanup so failing regressions cannot leak state.\n- Generator modules intended for reuse must be importable without parsing\n  arguments, exiting, mutating files, calling Git, or launching subprocesses.\n  Put orchestration in `main(argv=None)` and use a conventional guarded entry\n  point when refactoring for importability.\n\n## Output equivalence\n\n- Establish an exact pre-refactor baseline and keep testability refactors\n  separate from behavior fixes.\n- Testability refactors must preserve generated bytes, paths, ordering,\n  comments, whitespace, guards, encoding, newlines, modes, and symlink targets.\n- Compare fixes to the latest approved baseline while retaining the original\n  refactor baseline as an immutable reference.\n- Return-value, status, diagnostic, and CLI changes must not alter generated\n  files unless that is their documented purpose.\n- For translator changes, run a repository-scale comparison covering C API,\n  CppToC, CToCpp, wrapper, dylib, and GYPI outputs.\n- For distribution changes, compare the complete normalized tree. Compare\n  archive member paths, types, uncompressed bytes, and modes; normalize archive\n  timestamps only. Do not use raw archive-container hashes as equivalence.\n- Use the same Python interpreter as the recorded baseline. Python-version\n  differences can change comment wrapping and produce misleading byte deltas.\n\n## Bug-fix workflow\n\n- Reproduce a bug with a focused regression before changing production code.\n- Keep coverage/refactor checkpoints separate from behavior fixes so output\n  differences cannot be attributed to the wrong change.\n- Keep unrelated bugs independently reviewable. Closely related instances of\n  the same root cause may be grouped when explicitly requested.\n\n## Formatting and validation\n\n- From the CEF root, format only explicit changed Python paths:\n\n  ```sh\n  python3 tools/fix_style.py tools/make_example.py tools/make_example_test.py\n  ```\n\n- Inspect formatter output immediately. The formatter may rewrap unrelated\n  legacy code; revert that churn with targeted patches.\n- Compile every changed generator, helper, and test.\n- Run `git diff --check` and scan untracked files for trailing whitespace.\n- Re-run focused tests after formatting, then run the complete suite twice.\n","tools/CLAUDE.md":"@AGENTS.md\n","tools/cefbuilds/README.md":"# CEF Builds JSON Tools\n\nTools for generating and maintaining the JSON index files used by the\n[CEF Builds](https://cef-builds.spotifycdn.com/index.html) CDN and the CEF\ninstaller.\n\n## Files\n\n### Core libraries\n\n- **`cef_json_builder.py`** — Builds and maintains the master `index.json` file\n  that contains the full catalog of CEF binary distributions across all\n  platforms, versions, and channels. Handles file metadata (name, size, sha1,\n  last_modified), Chromium version mapping, and sandbox compatibility hashes.\n\n- **`cef_installer_builder.py`** — Generates installer-optimized CDN query files\n  from a populated `cef_json_builder` instance. Produces lightweight JSON files\n  designed for efficient HTTP HEAD timestamp checks by the CEF installer.\n\n### Data files\n\n- **`revoked.json`** — Manually maintained list of revoked CEF versions. Revoked\n  versions are excluded from all installer-generated JSON output. The installer\n  also fetches this file from the CDN and refuses to install any listed version.\n\n### Examples and tests\n\n- **`cef_json_builder_example.py`** — Example script demonstrating\n  `cef_json_builder` usage. Creates and updates a local `index.json` with fake\n  file data.\n\n- **`cef_json_builder_test.py`** — Unit tests for `cef_json_builder`.\n\n- **`cef_installer_builder_test.py`** — Unit tests for `cef_installer_builder`.\n\n## CDN file formats\n\n### Master index\n\n- **`index.json`** — Full data index of all CEF binary distributions. Generated\n  by `cef_json_builder`. Keyed by platform, with version records sorted\n  newest-first by file last_modified timestamp.\n\n### Installer query files\n\nGenerated by `cef_installer_builder` from the master index:\n\n- **`stable.txt`** — Current stable milestone number (e.g., `137`).\n\n- **`{milestone}.json`** (e.g., `137.json`) — Newest build per platform for a\n  given milestone. Used by the installer to check if an update is available.\n\n- **`{milestone}_{platform}.json`** (e.g., `137_windows64.json`) — All builds\n  for a milestone+platform combination, sorted newest-first.\n\n- **`{abi_hash}_{platform}.json`** (e.g., `abc123def4567890_windows64.json`) —\n  All builds compatible with a given ABI hash and platform across all milestones,\n  sorted newest-first. Windows platforms only (tied to `chrome_elf.dll` /\n  Chromium sandbox ABI).\n\n## Concepts\n\n### Platforms\n\nSupported platforms: `linux32`, `linux64`, `linuxarm`, `linuxarm64`,\n`macosarm64`, `macosx64`, `windows32`, `windows64`, `windowsarm64`.\n\n### Distribution types\n\nEach version may have files of these types: `standard`, `minimal`, `client`,\n`tools`, `release_symbols`, `debug_symbols`, `signed`.\n\nThe `signed` type contains code-signed archives with catalog files, used by the\ninstaller for verified installation.\n\n### Channels\n\nVersions belong to either the `stable` or `beta` channel.\n\n### Version formats\n\n- **New-style**: `137.3.5+g62d140e+chromium-137.0.7204.6`\n  - Short version: `137.3.5` (everything before the first `+`)\n  - Milestone: `137` (major version number)\n- **Old-style**: `3.2704.1414.g185cd6c` (predates the installer format)\n\n### ABI hash (`sandbox_compat`)\n\nA 16-character hex string identifying the Windows sandbox ABI compatibility\nlevel. Derived from `cef_api_versions.json` on GitHub. Versions sharing the same\nABI hash can use the same `chrome_elf.dll` and are interchangeable from the\nsandbox's perspective.\n\n### Revocation\n\nThe `revoked.json` file lists versions that must not be installed. When passed\nto `cef_installer_builder`, revoked versions are automatically excluded from\nall generated output. The installer also fetches this file from the CDN at\nruntime and refuses to install any listed version.\n\nEntries can revoke a single version or a range of versions:\n\n```json\n{\n  \"revoked_versions\": [\n    {\n      \"version\": \"137.1.0\",\n      \"reason\": \"CVE-2024-XXXXX: critical sandbox escape\",\n      \"revoked_at\": \"2024-01-15T00:00:00Z\"\n    },\n    {\n      \"version_min\": \"138.0.0\",\n      \"version_max\": \"138.2.99\",\n      \"reason\": \"CVE-2024-YYYYY: affects all 138.0–138.2 builds\",\n      \"revoked_at\": \"2024-02-01T00:00:00Z\"\n    }\n  ]\n}\n```\n\n**Single version** (point revocation):\n- `version` — Short version string (e.g., `137.1.0`).\n\n**Version range** (inclusive):\n- `version_min` — Inclusive lower bound (e.g., `138.0.0`).\n- `version_max` — Inclusive upper bound (e.g., `138.2.99`).\n\n**Common fields:**\n- `reason` — Human-readable explanation (CVE ID, bug reference, etc.).\n- `revoked_at` — ISO 8601 timestamp of when the revocation was added.\n\nA single-version entry using `version` is equivalent to setting both\n`version_min` and `version_max` to the same value. If both `version` and\n`version_min`/`version_max` are present, the range fields take precedence.\n\n## Running tests\n\n```bash\ncd cef/tools/cefbuilds\npython3 -m unittest cef_json_builder_test -v\npython3 -m unittest cef_installer_builder_test -v\n```\n","tools/clang/CLAUDE.md":"# CEF Clang Tools - Claude Code Instructions\n\nThis file provides guidance to Claude Code when working with CEF clang tools.\n\n## Overview\n\nThe `cef_cpp_rewriter` tool is a clang AST-based rewriter for C++20 modernization.\nIt uses Clang's LibTooling and AST matchers to perform type-aware transformations\nthat cannot be done with simple regex.\n\n**Supported transformations:** `.contains()`, structured bindings, iterator loops,\nDISALLOW_COPY_AND_ASSIGN. See [TRANSFORMS.md](TRANSFORMS.md) for complete documentation.\n\n**Important:** CEF is a separate git repository within chromium/src. Chromium's\nclang tool scripts use git commands that don't work across repository boundaries.\nUse the CEF-specific scripts in `cef/tools/clang/scripts/` instead.\n\n## Key Files\n\n- `cef/tools/clang/cef_cpp_rewriter/CefCppRewriter.cpp` - Main tool implementation\n- `cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt` - Build configuration\n- `cef/tools/clang/scripts/build_clang_rewriter.sh` - Bootstrap script\n- `cef/tools/clang/scripts/package_standalone.sh` - Package for standalone use\n- `cef/tools/clang/standalone/` - Standalone distribution files\n- `cef/tools/clang/cef_cpp_rewriter/tests/` - Test cases\n\n## Prerequisites\n\n**Python 3.10+ required.** Chromium's build scripts use type union syntax that requires Python 3.10+. On macOS:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\n```\n\n## Development Workflow\n\n### Building the Tool\n\nAfter modifying `CefCppRewriter.cpp`:\n\n```bash\n# Fast incremental rebuild (~seconds)\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Never re-run `build_clang_rewriter.sh`** unless the build directory was deleted.\nIt rebuilds clang from scratch (~30 minutes).\n\n### Testing Matchers with clang-query\n\n```bash\nexport PATH=$PATH:third_party/llvm-build/Release+Asserts/bin\nclang-query /tmp/test.cc --\n```\n\n### Generating compile_commands.json for Manual Testing\n\nThe `test_tool.py` script generates this automatically, but for manual testing:\n\n```bash\n# macOS (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -isysroot $(xcrun --show-sdk-path) -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Linux (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Run the tool (--disable-path-filter needed for test files)\nthird_party/llvm-build/Release+Asserts/bin/cef_cpp_rewriter \\\n  --disable-path-filter -p $TEST_DIR $TEST_DIR/contains-original.cc\n```\n\n### Running Tests\n\n```bash\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n### Debugging\n\n1. Add `dumpColor()` calls in `run()` to visualize matched AST nodes\n2. Return 1 from `main()` to see tool output (run_tool.py hides output on success)\n3. Dump AST: `clang++ -Xclang -ast-dump -std=c++20 file.cc`\n\n## Important Constraints\n\n1. **Symlink required**: The tool must be symlinked to `tools/clang/cef_cpp_rewriter`\n2. **Do not transform std::string**: Only associative containers have C++20 `.contains()`\n3. **Same container check**: Verify `find()` and `end()` are called on the same object\n4. **Skip macros**: Don't transform code inside macro expansions\n5. **CEF paths only**: Only transform files containing `/cef/` in their path\n\n## Compatibility Requirements\n\nCEF targets C++20. All transformations must work with these minimum toolchain versions:\n\n- GCC 10 (CEF minimum)\n- macOS 12.0 deployment target\n\nFeatures to AVOID (incompatible):\n\n- `std::string::contains()` - C++23, needs GCC 11+\n- `std::format` - needs GCC 13+ and macOS 13.3+\n- `using enum` - needs GCC 11+\n\n## Adding New Transformations\n\n### Quick Steps\n\n1. Add a command-line flag in `CefCppRewriter.cpp`:\n    ```cpp\n    static llvm::cl::opt<bool> EnableNewFeature(\"new-feature\",\n        llvm::cl::desc(\"Enable new feature transformation\"),\n        llvm::cl::init(true));\n    ```\n\n2. Create a new `MatchCallback` class for the transformation\n\n3. Add matcher to `match_finder` in `main()` guarded by the flag\n\n4. Add test files: `tests/newfeature-original.cc` and `tests/newfeature-expected.cc`\n\n5. Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n   (test_tool.py generates compile_commands.json automatically)\n\n### Full Implementation Checklist Template\n\nUse this checklist when implementing any new transformation:\n\n```markdown\n### Phase N: [Transformation Name]\n**Priority:** Nth | **Complexity:** Low/Medium/High | **Compat:** GCC X+\n\n[Brief description of the transformation]\n\n**Before/After Example:**\n```cpp\n// Before\n[old code pattern]\n\n// After\n[new code pattern]\n```\n\n**Checklist:**\n- [ ] Verify compatibility with GCC 10 and macOS 12.0 deployment target\n- [ ] Add `--flag-name` command-line flag (default: true/false)\n- [ ] Implement `TransformNameRewriter` class with:\n  - [ ] `run()` method that handles matched nodes\n  - [ ] Macro expansion filtering (`isMacroID()`, `isMacroBodyExpansion()`)\n  - [ ] System header filtering (`isInSystemHeader()`)\n  - [ ] Path filtering (skip non-CEF files unless `--disable-path-filter`)\n  - [ ] Deduplication via `processed_locations_` set\n- [ ] Create AST matcher(s) - test with `clang-query` first\n- [ ] Add matcher to `match_finder` in `main()` guarded by flag\n- [ ] Create test files: `transform-name-original.cc`, `transform-name-expected.cc`\n- [ ] Create negative test cases: `transform-name-negative-original.cc` (copy to `-expected.cc`)\n- [ ] Rebuild tool: `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n- [ ] Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n- [ ] Run on CEF code: `python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool --tool-args=\"--flag-name\" cef/libcef cef/libcef_dll cef/tests`\n- [ ] Review diffs and verify correctness\n- [ ] Build CEF to verify no compile errors\n- [ ] Run CEF tests to verify no regressions\n- [ ] Search for skipped instances (macros, edge cases) using grep\n- [ ] Manually transform skipped instances if appropriate\n- [ ] Update TRANSFORMS.md with transformation details\n- [ ] Update CLAUDE.md tool arguments table\n- [ ] Update README.md tool arguments table and transformations list\n```\n\n### Rewriter Class Template\n\n```cpp\nclass NewFeatureRewriter : public MatchFinder::MatchCallback {\n public:\n  explicit NewFeatureRewriter(OutputHelper* output) : output_helper_(*output) {}\n\n  void reset() { processed_locations_.clear(); }\n\n  void run(const MatchFinder::MatchResult& result) override {\n    const auto* matched_node = result.Nodes.getNodeAs<NodeType>(\"bindingName\");\n    if (!matched_node) return;\n\n    const SourceManager& sm = *result.SourceManager;\n    const LangOptions& opts = result.Context->getLangOpts();\n\n    // Skip macros\n    if (matched_node->getBeginLoc().isMacroID() ||\n        sm.isMacroBodyExpansion(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Skip system headers\n    if (sm.isInSystemHeader(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Deduplicate\n    unsigned offset = sm.getFileOffset(matched_node->getBeginLoc());\n    if (processed_locations_.count(offset)) return;\n\n    // Path filter\n    if (!DisablePathFilter) {\n      StringRef filename = sm.getFilename(matched_node->getBeginLoc());\n      if (!filename.contains(\"/cef/\")) return;\n    }\n\n    processed_locations_.insert(offset);\n\n    // Generate replacement\n    std::string replacement = /* ... */;\n    CharSourceRange range = CharSourceRange::getTokenRange(\n        matched_node->getSourceRange());\n    output_helper_.Replace(range, replacement, sm, opts);\n  }\n\n private:\n  OutputHelper& output_helper_;\n  std::set<unsigned> processed_locations_;\n};\n```\n\n### Common Pitfalls\n\n1. **Iterator comparisons use overloaded operators**: Use `cxxOperatorCallExpr(hasOverloadedOperatorName(\"!=\"))` not `binaryOperator`\n2. **Integer literals need implicit cast handling**: Use `ignoringImpCasts(integerLiteral(...))`\n3. **Pointer access needs separate matching**: Include `hasType(pointsTo(...))` in an `anyOf()`\n4. **Token vs char ranges**: `getTokenRange()` includes full last token, `getCharRange()` is exact\n5. **Don't transform std::string methods**: Many string methods have same names but different semantics\n\n## Running the Tool on CEF Code\n\n```bash\n# Create build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool && cp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run all transformations (default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--contains=false --structured-bindings\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\nExample: `--tool-args=\"--only=iterator-loops\"` runs only the iterator-loops transformation.\n\n## Critical Reminders\n\n1. **Symlink required**: `test_tool.py` looks for tools in `tools/clang/`, so the symlink must exist\n2. **Test naming**: Files must be named `*-original.cc` and `*-expected.cc` (not `-test.cc`)\n3. **Do not transform `std::string::find()`**: Only associative containers have C++20 `.contains()`\n4. **Incremental builds**: Use `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n5. **Do not re-run build.py**: It deletes everything and rebuilds from scratch (~30 min)\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory (from chromium/src)\n./cef/tools/clang/scripts/package_standalone.sh /path/to/cpp_rewriter\n\n# This creates a self-contained distribution:\n# /path/to/cpp_rewriter/\n# ├── bin/cpp_rewriter           # The tool binary (renamed from cef_cpp_rewriter)\n# ├── lib/clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper (auto-detects resource dir)\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\n**Key differences from CEF usage:**\n\n- Uses `--path-filter` for substring matching instead of default `/cef/` filter\n- Bundled clang headers allow tool to work without matching system clang\n- No `--generate-compdb` - requires pre-existing `compile_commands.json`\n- `CMAKE_EXPORT_COMPILE_COMMANDS` only works with Ninja/Makefiles generators (not Xcode/VS)\n\nSee `standalone/README.md` for complete standalone usage documentation.\n","tools/clang/README.md":"# CEF Clang Tools\n\nThis directory contains clang-based tools for CEF code modernization and refactoring.\n\n## Tools\n\n### cef_cpp_rewriter\n\nA clang AST-based rewriter tool for automating C++20 modernization of CEF code.\n\n**Supported transformations:**\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for complete documentation of all transformations, command-line flags, and examples.\n\n## Prerequisites\n\n- Chromium checkout with CEF\n- **Python 3.10+** (Chromium's build scripts require it)\n- ~30 minutes for initial clang bootstrap\n\n**Note:** CEF is a separate git repository within chromium/src. Chromium's clang\ntool scripts (`run_tool.py`, `test_tool.py`, `apply_edits.py`) use git commands\nthat don't work across repository boundaries. This directory provides CEF-specific\nreplacements: `run_tool.py`, `test_tool.py`, and `apply_edits.py`.\n\n### Python Version\n\nmacOS ships with Python 3.9 which is too old. Install Python 3.12 via Homebrew:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\npython3 --version  # Should show 3.12.x\n```\n\nAdd the export line to `~/.zshrc` to make it permanent.\n\n## Quick Start\n\n### Initial Setup (one-time, ~30 minutes)\n\n```bash\n# From chromium/src directory\n./cef/tools/clang/scripts/build_clang_rewriter.sh\n```\n\nThis will:\n\n1. Create a symlink from `tools/clang/cef_cpp_rewriter` to the CEF tool\n2. Bootstrap clang with the tool (~30 minutes)\n\n**Warning:** The clang bootstrap updates `third_party/llvm-build/`, which will\ninvalidate all existing Chromium/CEF build directories and trigger a full\nrebuild the next time you build. Plan accordingly.\n\n### Running the Tool\n\n```bash\n# Create a build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool\ncp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run the tool on CEF code (all transformations enabled by default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--structured-bindings --contains=false\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Or run on all CEF files (omit path arguments)\n# python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool\n\n# Process and apply the edits\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\n**Examples:**\n```bash\n# Run only iterator-loops transformation\n--tool-args=\"--only=iterator-loops\"\n\n# Run only contains and structured-bindings\n--tool-args=\"--only=contains,structured-bindings\"\n\n# Disable specific transformation (all others still run)\n--tool-args=\"--contains=false\"\n```\n\n### Incremental Rebuilds\n\nAfter modifying `CefCppRewriter.cpp`, rebuild quickly with:\n\n```bash\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Do not re-run `build_clang_rewriter.sh`** - it rebuilds everything from scratch.\n\n## Testing\n\n```bash\n# Run tool tests\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n## Compatibility\n\nCEF targets C++20. See [TRANSFORMS.md](TRANSFORMS.md) for minimum toolchain versions.\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory\n./cef/tools/clang/scripts/package_standalone.sh /path/to/target\n\n# This creates:\n# /path/to/target/\n# ├── bin/cpp_rewriter           # The tool binary\n# ├── lib/clang/<version>/       # Bundled clang headers\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\nThe standalone distribution is self-contained and includes bundled clang headers\nso it works without requiring a matching system clang installation.\n\n**Usage on any CMake project:**\n```bash\ncd my-project\n\n# Generate compile_commands.json (requires Ninja or Makefiles generator)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Run the rewriter\n/path/to/target/scripts/run_rewriter.py -p build src/ \\\n  | /path/to/target/scripts/apply_edits.py --base-dir build\n```\n\nSee `standalone/README.md` for complete standalone usage documentation.\n\n## Directory Structure\n\n```\ncef/tools/clang/\n├── cef_cpp_rewriter/\n│   ├── CMakeLists.txt\n│   ├── CefCppRewriter.cpp\n│   ├── OutputHelper.h\n│   ├── OutputHelper.cpp\n│   └── tests/\n│       ├── contains-original.cc\n│       ├── contains-expected.cc\n│       ├── contains-negative-original.cc\n│       ├── contains-negative-expected.cc\n│       ├── disallow-copy-original.cc\n│       ├── disallow-copy-expected.cc\n│       ├── disallow-copy-negative-original.cc\n│       ├── disallow-copy-negative-expected.cc\n│       ├── structured-bindings-original.cc\n│       ├── structured-bindings-expected.cc\n│       ├── structured-bindings-negative-original.cc\n│       ├── structured-bindings-negative-expected.cc\n│       ├── iterator-loops-original.cc\n│       ├── iterator-loops-expected.cc\n│       ├── iterator-loops-negative-original.cc\n│       └── iterator-loops-negative-expected.cc\n├── scripts/\n│   ├── apply_edits.py            # Applies edits (no git dependency)\n│   ├── build_gen_targets.sh      # Build CEF-related gen targets only\n│   ├── build_clang_rewriter.sh   # Bootstrap clang with the tool\n│   ├── package_standalone.sh     # Package for standalone use\n│   ├── process_edits.py          # Adds markers, deduplicates edits\n│   ├── run_tool.py               # Run tool on CEF files\n│   └── test_tool.py              # CEF-specific test harness\n├── standalone/\n│   ├── README.md                 # Standalone usage documentation\n│   └── run_rewriter.py           # Standalone wrapper script\n├── CLAUDE.md\n├── README.md\n└── TRANSFORMS.md                 # Transformation documentation\n```\n\n## Maintenance\n\nThis tool is not regularly tested. It may need updates when:\n\n| Trigger | Likely Fix |\n|---------|------------|\n| Chromium updates `tools/clang/` infrastructure | Update `CMakeLists.txt`, check `build.py` flags |\n| LLVM/Clang API changes | Update AST matcher syntax, check deprecations in Clang doxygen |\n| CEF adopts C++23 | Add `flat_map`/`flat_set` container types to matcher |\n| Build fails after Chromium update | Compare with current `tools/clang/ast_rewriter/` example |\n\n### Diagnosing Build Failures\n\nIf the tool fails to build after a Chromium update:\n\n1. Check if `ast_rewriter` still exists and builds:\n    ```bash\n    python3 tools/clang/scripts/build.py --bootstrap --extra-tools ast_rewriter\n    ```\n\n2. Compare CMakeLists.txt with the current ast_rewriter version:\n    ```bash\n    diff cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt tools/clang/ast_rewriter/CMakeLists.txt\n    ```\n\n3. Check for API changes in Clang's AST matchers (review Clang release notes)\n\n### Cleanup\n\nAfter running the tool, you may want to remove the symlink:\n\n```bash\nrm tools/clang/cef_cpp_rewriter  # Removes symlink only, not CEF source\n```\n\n## Resources\n\n- Chromium clang tool documentation: `docs/clang_tool_refactoring.md`\n- Chromium example: `tools/clang/ast_rewriter/`\n- [AST Matcher Reference](https://clang.llvm.org/docs/LibASTMatchersReference.html)\n- [LibTooling Tutorial](https://clang.llvm.org/docs/LibASTMatchersTutorial.html)\n","tools/clang/standalone/README.md":"# C++ Rewriter Tool\n\nA clang-based AST rewriter for C++20 modernization. This tool performs\ntype-aware code transformations that cannot be done with simple regex,\nsuch as replacing `map.find(x) != map.end()` with `map.contains(x)`.\n\n## Distribution Contents\n\nThis is a self-contained distribution that includes everything needed to run:\n\n```\ncpp_rewriter/\n├── bin/\n│   └── cpp_rewriter           # The clang-based rewriter tool\n├── lib/\n│   └── clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n│       └── include/\n├── scripts/\n│   ├── run_rewriter.py        # Main wrapper script\n│   ├── apply_edits.py         # Applies generated edits to files\n│   └── process_edits.py       # Deduplicates and formats edits\n└── README.md\n```\n\nThe bundled `lib/clang/` headers are automatically detected and used by the\nwrapper script, so the tool works without requiring a matching system clang.\n\n## Prerequisites\n\n- A C++ project with a `compile_commands.json` file\n- Python 3.6+\n\n## Generating compile_commands.json\n\nThe tool requires a compilation database to understand your project's\nbuild configuration. Here's how to generate one for common build systems:\n\n### CMake\n\n**Important:** `CMAKE_EXPORT_COMPILE_COMMANDS` only works with **Makefile**\nand **Ninja** generators. It does NOT work with Xcode or Visual Studio generators.\n\n```bash\n# Using Ninja (recommended)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Using Unix Makefiles\ncmake -G \"Unix Makefiles\" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# compile_commands.json is now in build/\n```\n\nIf you normally use Xcode/Visual Studio, create a separate build directory\njust for tooling:\n\n```bash\n# Keep your Xcode build, add a parallel Ninja build for tools\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build-tools\n# Use build-tools/compile_commands.json with the rewriter\n```\n\n### Meson\n\n```bash\nmeson setup build\n# compile_commands.json is automatically generated in build/\n```\n\n### Bear (for Make-based projects)\n\n```bash\n# Install Bear: https://github.com/rizsotto/Bear\nbear -- make\n# compile_commands.json is generated in current directory\n```\n\n### Ninja\n\n```bash\nninja -C build -t compdb > build/compile_commands.json\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Run on all files in compile_commands.json\n./scripts/run_rewriter.py -p /path/to/build | ./scripts/apply_edits.py --base-dir /path/to/build\n\n# Run on specific source directories only\n./scripts/run_rewriter.py -p build src/ include/ | ./scripts/apply_edits.py --base-dir build\n```\n\n### Filter by Path Pattern\n\nUse `--path-filter` with a substring to process only matching files:\n\n```bash\n# Only process files containing \"src/core/\" in their path\n./scripts/run_rewriter.py -p build --path-filter \"src/core/\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Disable Specific Transformations\n\n```bash\n# Disable structured bindings transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--structured-bindings=false\" | ./scripts/apply_edits.py --base-dir build\n\n# Run only the .contains() transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--only=contains\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Verbose Output\n\n```bash\n# Show progress\n./scripts/run_rewriter.py -p build -v src/ 2>&1 | tee /tmp/edits.txt\n./scripts/apply_edits.py --base-dir build < /tmp/edits.txt\n```\n\n## Available Transformations\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nAll transformations are enabled by default. Use `--flag=false` to disable specific ones,\nor `--only=<list>` to run only specific transformations.\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags,\nbefore/after examples, supported containers, and edge cases.\n\n## Troubleshooting\n\n### \"compile_commands.json not found\"\n\nMake sure you've generated the compilation database. See the\n\"Generating compile_commands.json\" section above.\n\n### \"No files found matching...\"\n\n- Check that the path filter matches your file paths\n- Use `-v` for verbose output to see which files are being processed\n- Try running without a path filter first\n\n### Transformations not applying\n\n- The tool only transforms code, not macro expansions\n- Some patterns may not match due to unusual formatting\n- Use `-v` to see error messages from the tool\n\n## Compatibility\n\nThe transformed code uses C++20 features. See [TRANSFORMS.md](TRANSFORMS.md) for\nminimum compiler requirements.\n\n## Building from Source\n\nThis tool is built as part of the CEF (Chromium Embedded Framework) project.\nSee the CEF repository for build instructions.\n","tools/claude/README.md":"# Tools and Detailed Instructions for CEF Development\n\nThis directory contains tools and detailed instructions for using coding\nagents to assist with CEF (Chromium Embedded Framework) development. Use these\nguides with models that benefit from explicit workflows, examples, and\nverification steps, including Claude Opus 4.x and GPT Terra.\n\nThe guides were originally written for Claude Code and retain their `CLAUDE_*`\nfilenames. Other coding agents can use them directly; adapt any Claude-specific\nsetup or file attachment syntax to your agent. For GPT Sol or other frontier\nmodels that work well with concise instructions, see the\n[GPT guides](../gpt/README.md) for concise patch and build instructions and\nexample prompts. For other tasks, newer frontier models can often discover the\nrelevant details themselves, using the detailed instruction files here as\nreference material when needed.\n\n***\n[TOC]\n***\n\n## Quick Navigation\n\n**Are you updating CEF to a new Chromium version?**\n\n→ See [CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md) for the complete workflow:\n\n- Fixing patches that fail to apply\n- Fixing build errors from API changes\n- Using analyzer scripts and verification tools\n\n**Are you developing a CEF application using a binary distribution?**\n\n→ See [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md) for implementing features:\n\n- Adding custom URL schemes\n- JavaScript-to-C++ communication\n- Network request interception\n- Popup window customization\n\n**Are you writing or debugging CEF unit tests?**\n\n→ See [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md) for working with ceftests:\n\n- Running existing unit tests\n- Creating new tests for CEF features\n- Debugging test failures and flakiness\n- Using TestHandler, RoutingTestHandler, and TestServer\n\n**Are you developing libcef internals (CEF implementation code)?**\n\n→ See [CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md) for libcef development patterns:\n\n- Adding new CEF APIs with proper versioning\n- Implementing WebContentsDelegate callbacks\n- Working with Chrome and Alloy browser styles\n- Finding and fixing NOTIMPLEMENTED() stubs\n\n**Are you syncing CEF base headers with Chromium?**\n\n→ See [CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md) for synchronizing `cef/include/base/` headers:\n\n- CEF-specific modifications (namespaces, includes, platform macros)\n- Files to sync vs files to preserve\n- Handling C++23 reverts\n- Step-by-step sync process\n\n**Are you cherry-picking commits from upstream CEF?**\n\n→ See [CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md) for cherry-picking commits that include patch files:\n\n- Extracting and applying source file changes from patches\n- Resaving patches with correct index hashes\n- Handling multiple patch files per commit\n- Recovery when things go wrong\n\n**Are you applying a Chromium commit to CEF as a patch?**\n\n→ See [CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md) for creating or updating CEF patches from Chromium commits:\n\n- Creating new patch files and adding to patch.cfg\n- Adding changes to existing patch files\n- Handling version differences between Chromium versions\n- Verifying patches can be reverted and reapplied\n\n**Are you improving unit test coverage?**\n\n→ See [CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md) for running and analyzing code coverage:\n\n- Human prerequisites for setting up coverage builds\n- Building and running tests with coverage instrumentation\n- Analyzing coverage reports to identify gaps\n- Workflow for improving function and line coverage\n\n## Files in This Directory\n\n### Documentation\n\n- **[CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md)** - Complete guide for updating CEF to new Chromium versions\n- **[CLAUDE.md.in](CLAUDE.md.in)** - Template for root CLAUDE.md (copied by setup_claude.py)\n- **[CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md)** - Instructions for syncing CEF base headers with Chromium\n- **[CLAUDE_BUILD_INSTRUCTIONS.md](CLAUDE_BUILD_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing build errors\n- **[CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md)** - Instructions for cherry-picking commits from upstream CEF that include patch files\n- **[CLAUDE_CLIENT_INSTRUCTIONS.md](CLAUDE_CLIENT_INSTRUCTIONS.md)** - Detailed instructions for Claude agents implementing features in CEF applications\n- **[CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md)** - Instructions for running and analyzing code coverage\n- **[CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md)** - Detailed instructions for Claude agents developing libcef internals (API versioning, WebContentsDelegate)\n- **[CLAUDE_PATCH_INSTRUCTIONS.md](CLAUDE_PATCH_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing patch failures\n- **[CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md)** - Instructions for applying Chromium commits to CEF as new or existing patches\n- **[CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md)** - Detailed instructions for Claude agents creating and running CEF unit tests\n- **[CLAUDE_WIKI_INSTRUCTIONS.md](CLAUDE_WIKI_INSTRUCTIONS.md)** - Bitbucket wiki formatting guidelines for Claude agents\n- **[CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md)** - Complete guide for CEF client application development\n- **[README.md](README.md)** - This file\n\n### Python Tools\n\n- **[analyze_build_output.py](analyze_build_output.py)** - Analyze and format ninja build output with error index\n- **[analyze_coverage_output.py](analyze_coverage_output.py)** - Analyze LLVM coverage reports and identify coverage gaps\n- **[analyze_patch_output.py](analyze_patch_output.py)** - Analyze and format `patch_updater.py` output with file movement detection\n- **[patch_utils.py](patch_utils.py)** - Shared utilities for patch analysis tools (file movement detection)\n- **[verify_patch.py](verify_patch.py)** - Verify that regenerated patches include all changes from reject files\n- **[format_wiki.py](format_wiki.py)** - Apply Bitbucket wiki formatting guidelines to markdown files (supports wildcards; also integrated into `../fix_style.py`)\n\n### Test Files\n\n- **[analyze_build_output_test.py](analyze_build_output_test.py)** - Unit tests for analyze_build_output.py\n- **[analyze_coverage_output_test.py](analyze_coverage_output_test.py)** - Unit tests for analyze_coverage_output.py\n- **[analyze_patch_output_test.py](analyze_patch_output_test.py)** - Unit tests for analyze_patch_output.py\n- **[patch_utils_test.py](patch_utils_test.py)** - Unit tests for patch_utils.py\n- **[verify_patch_test.py](verify_patch_test.py)** - Unit tests for verify_patch.py\n- **[format_wiki_test.py](format_wiki_test.py)** - Unit tests for format_wiki.py\n\n## Common Setup\n\nFor Chromium update workflows, run the setup script:\n\n```bash\ncd chromium/src/cef/tools\npython3 setup_claude.py\n```\n\nThis copies `CLAUDE.md.in` to the project root as `chromium/src/CLAUDE.md`, enabling Claude Code to understand the Chromium/CEF codebase structure.\n\n## Formatting Files\n\nThe `fix_style.py` tool in `//cef/tools/` formats C/C++, Python, and Markdown files:\n\n```bash\n# From chromium/src/cef/tools directory:\n\n# Format single markdown file\npython3 fix_style.py claude/CLAUDE_TEST_INSTRUCTIONS.md\n\n# Format all CLAUDE instruction files\npython3 fix_style.py claude/CLAUDE_*.md\n\n# Format all markdown files in claude directory\npython3 fix_style.py claude/*.md\n\n# Format all staged files (including markdown)\npython3 fix_style.py staged\n```\n\nThe markdown formatter applies [Bitbucket wiki formatting guidelines](CLAUDE_WIKI_INSTRUCTIONS.md) (blank lines before lists, 4-space indentation, etc.).\n\n## Tips for Working with Claude Code\n\nThese tips apply to both Chromium updates and client development:\n\n### 1. Provide Context\n\nAlways include relevant version numbers or distribution details:\n\n**For Chromium updates:**\n```\nOld version: 139.0.7258.0\nNew version: 140.0.7339.0\n```\n\n**For client development:**\n```\nCEF binary distribution: cef_binary_142.0.10+g29548e2+chromium-142.0.7444.135_macosarm64\n```\n\n### 2. Attach Relevant Files\n\nUse `@filename` to attach files Claude should read:\n\n- `@cef/tools/claude/patch_analysis.txt` - Analyzed patch output\n- `@cef/tools/claude/build_analysis.txt` - Analyzed build output\n- `@cef/tools/claude/CLAUDE_CHERRY_PICK_INSTRUCTIONS.md` - Cherry-picking upstream commits\n- `@cef/tools/claude/CLAUDE_CLIENT_INSTRUCTIONS.md` - Client development guide\n- `@cef/tools/claude/CLAUDE_SRC_PATCH_INSTRUCTIONS.md` - Applying Chromium commits as patches\n- `@cef/tools/claude/CLAUDE_TEST_INSTRUCTIONS.md` - CEF unit testing guide\n\n**Tip:** In large directory structures like `chromium/src`, the `@` syntax can be slow. Use `//` syntax for workspace-relative paths instead (e.g., `//cef/tools/claude/patch_analysis.txt`).\n\n### 3. Let Claude Work Systematically\n\nDon't interrupt mid-stream unless necessary. Claude will:\n\n- Create TODO lists\n- Work through items one by one\n- Report progress regularly\n- Ask for help when stuck\n\n### 4. Use Incremental Prompts\n\nFor large tasks, you can guide Claude incrementally:\n\n**For Chromium updates:**\n```\n1. \"Start fixing patches using @CLAUDE_PATCH_INSTRUCTIONS.md\"\n2. [Claude works for a while]\n3. \"Good progress. Continue with the remaining patches.\"\n4. [Claude finishes]\n5. \"Now let's fix build errors using @CLAUDE_BUILD_INSTRUCTIONS.md\"\n```\n\n**For unit testing:**\n```\n1. \"Create tests for the new feature using @CLAUDE_TEST_INSTRUCTIONS.md\"\n2. [Claude creates tests]\n3. \"Run the tests and fix any failures\"\n4. [Claude debugs and fixes]\n5. \"Good, now verify they work in both Chrome and Alloy styles\"\n```\n\n### 5. Ask for Summaries\n\nAfter a session:\n```\nPlease summarize all the changes you made, organized by category.\n```\n\nClaude can provide a detailed summary for documentation or commit messages.\n\n### 6. Use the Analyzers Proactively\n\nFor Chromium updates, run the analyzers yourself first to understand the scope:\n\n**For patches:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_patch_output.py patch_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > patch_analysis.txt\n```\n\n**For build errors:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_build_output.py build_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > build_analysis.txt\n```\n\nThen share the analysis files with Claude.\n\n## Getting Help\n\n### For Issues with Tools\n\n- Check the guide files and instruction files listed above for usage examples\n- Check analyzer script help: `python3 analyze_patch_output.py --help`\n\n### For Issues with CEF\n\n- CEF wiki: https://github.com/chromiumembedded/cef/blob/master/docs/README.md\n- CEF forums: https://magpcss.org/ceforum/\n- CEF issue tracker: https://github.com/chromiumembedded/cef/issues\n\n### For Issues with Claude Code\n\n- Claude Code documentation: https://docs.claude.com/claude-code\n- Improve prompts with more context and specific examples\n- Break large tasks into smaller, more manageable pieces\n\n## Contributing\n\nIf you improve these tools or instructions:\n\n1. Test with a real Chromium update, client development task, or unit testing workflow\n2. Document what you changed and why\n3. Update the appropriate guide ([CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md), [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md), or [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md))\n4. Share improvements with the CEF community\n\n## License\n\nThese tools are part of the CEF project and follow the same license as CEF (BSD license).\n","tools/debug/ax_viewport_collapse/README.md":"# ax_viewport_collapse Debug Tools\n\nManual verification tools for the `ax_viewport_collapse` CefBrowserSettings feature.\nThese connect to a running cefclient via CDP to inspect the accessibility tree.\n\n## Prerequisites\n\n```\npython3 -m pip install websocket-client\n```\n\n## Usage\n\n### 1. Launch cefclient with remote debugging\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\n```\n\nThe `--ax-viewport-collapse` flag maps to `CefBrowserSettings.ax_viewport_collapse = STATE_ENABLED` in cefclient.\n\nTo load the test page directly:\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse --url=file:///<path>/test_viewport_collapse.html\n```\n\n### 2. Run the verification script\n\n```\npython3 verify_viewport_collapse.py\n```\n\nOr navigate to a URL first:\n\n```\npython3 verify_viewport_collapse.py --url https://example.com\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `--host` | CDP host (default: `127.0.0.1`) |\n| `--port` | CDP port (default: `9222`) |\n| `--url` | Navigate to URL before fetching tree |\n| `--raw` | Print full JSON response instead of summary |\n\n### Comparing with/without collapse\n\nRun two cefclient instances on different ports:\n\n```\ncefclient.exe --cache-path=<path1> --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\ncefclient.exe --cache-path=<path2> --remote-debugging-port=9223 --remote-allow-origins=*\n```\n\n```\npython3 verify_viewport_collapse.py --port 9222 --raw > with.json\npython3 verify_viewport_collapse.py --port 9223 --raw > without.json\ndiff with.json without.json\n```\n\n### Expected output (with collapse enabled)\n\n```\nAX Tree Summary\n============================================================\nTotal nodes returned:  77\n  Ignored:             3\n  Full (with children):70\n  Summary (collapsed): 4\n\nCollapsed summary nodes (off-screen landmarks/headings):\n------------------------------------------------------------\n  region: \"Content preferences\"\n  region: \"Audio quality\"\n  region: \"Display\"\n  region: \"Storage\"\n```\n\nOff-screen landmark sections appear as leaf nodes with role + name only. In-viewport nodes are fully serialized with children.\n\n## Files\n\n- `verify_viewport_collapse.py` — CDP script that calls `Accessibility.getFullAXTree()` and prints a summary or raw JSON\n- `test_viewport_collapse.html` — Test page with 6 landmark sections, 2 in viewport and 4 pushed off-screen by a spacer\n","tools/gpt/README.md":"# GPT Instructions for CEF Updates\n\nUse these guides when asking a coding agent to update CEF patches or fix build\nerrors during a Chromium update. The GPT guides give Sol a short overview of\nwhat to do and how to verify the result. They link to the existing Claude\nguides for detailed commands, examples, and troubleshooting.\n\n## Choosing a model\n\n| Model | Starting effort | Guides to use |\n| --- | --- | --- |\n| GPT-6.1 Sol | Low | The GPT guides in this directory |\n| GPT-5.6 Terra | Choose for your task | The Claude guides in `cef/tools/claude/` |\n\nFor Sol, start with low effort and use the Sol examples below. The agent can\nconsult the linked Claude guides as it works. For Terra, use the Terra examples,\nwhich point directly to the detailed Claude guides. Those guides work with\nother models despite their filenames.\n\nSelect the model and effort in your coding agent before sending the prompt.\nThe instruction files describe the work; model selection is a separate setting.\n\nThese recommendations are a starting point for trying the workflows on real\nupdates. Adjust the GPT model and reasoning effort to balance speed and cost\nwhile meeting the same completion checks. Check whether the agent covers every\nfailed file, preserves CEF behavior, and saves source fixes into the patches.\nIf Sol gets stuck on a particular issue or cannot explain why a behavioral\nchange is correct, try that issue again at medium effort. When comparing speed\nand cost, include any follow-up work needed to correct the result.\n\n## Getting started\n\nBefore launching the agent, use the existing Chromium update guide to prepare\nyour checkout and the analysis for the phase you're working on:\n\n1. Review the [complete update workflow](../claude/CHROMIUM_UPDATE.md#complete-update-workflow)\n   for the order of checkout updates, patch repairs, builds, and testing.\n2. Check the [prerequisites](../claude/CHROMIUM_UPDATE.md#prerequisites) and\n   [setup](../claude/CHROMIUM_UPDATE.md#setup): you'll need a Chromium checkout\n   with CEF integration, Python 3, and the appropriate build configuration.\n   The `setup_claude.py` step installs context for Claude Code; it is not a\n   prerequisite for using the GPT prompts.\n3. For patch repairs, follow [Phase 1: Fixing Patches](../claude/CHROMIUM_UPDATE.md#phase-1-fixing-patches)\n   to capture `patch_updater.py` output and generate `patch_analysis.txt` with\n   your old and new Chromium versions. Then use the patch prompt below.\n4. Once the patches apply cleanly, follow [Phase 2: Fixing Build Errors](../claude/CHROMIUM_UPDATE.md#phase-2-fixing-build-errors)\n   to capture a build of your chosen target and generate `build_analysis.txt`.\n   Then use the build prompt below.\n\nStart your coding agent from the `chromium/src` checkout root. Copy one of the\ncomplete prompts below, then replace the Chromium versions and analysis path\nwith yours. For a build task, also set your output directory and build target.\nAll paths in the prompts are relative to `chromium/src`.\n\nUse the analysis files produced by the existing tools in `cef/tools/claude/`:\n\n- `patch_analysis.txt` lists failed patches and files.\n- `build_analysis.txt` lists build errors and points to the relevant sections\n  of `build_output.txt`.\n\nThe build examples include permission to fix Chromium files outside `cef/`\nwhen custom CEF patches cause their build failures. Keep that instruction if\nit applies to your update: it tells the agent to save those fixes into the\nassociated CEF patches and overrides the detailed build guide's usual scope.\n\n## Example prompts for Sol at low effort\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/gpt/GPT_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. Fix those build\nerrors and re-save the associated CEF patch files using\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n\n## Example prompts for Terra\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. You should also\nfix those build errors and re-save the associated CEF patch files using\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md. This extends the build\nguide's default restriction to files under cef.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n"},"files":{"docs/architecture.md":"This page provides an overview of the CEF architecture.\n\n**Contents**\n\n- [Overview](#overview)\n- [Dependencies](#dependencies)\n- [Versions](#versions)\n- [History](#history)\n- [Modern Architecture](#modern-architecture)\n- [Common API Usage](#common-api-usage)\n- [C Wrapper API](#c-wrapper-api)\n- [CEF1 (Discontinued)](#cef1-discontinued)\n  - [API Usage](#api-usage)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n- [CEF2 (Discontinued)](#cef2-discontinued)\n- [CEF3](#cef3)\n  - [API Usage](#api-usage)\n  - [Process Considerations](#process-considerations)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n    - [Alloy Runtime Classes](#alloy-runtime-classes)\n    - [Chrome Runtime Classes](#chrome-runtime-classes)\n\n---\n\n# Overview\n\nThe Chromium Embedded Framework (CEF) is an open source project founded by Marshall Greenblatt in 2008 to develop a Web browser control based on the [Google Chromium](http://www.chromium.org/Home) project. CEF currently supports a range of programming languages and operating systems and can be easily integrated into both new and existing applications. It was designed from the ground up with both performance and ease of use in mind. The base framework includes C and C++ programming interfaces exposed via native libraries that insulate the host application from Chromium and Blink implementation details. It provides close integration between the browser control and the host application, which can optionally control resource loading, navigation, context menus, printing, JavaScript bindings and more, while taking advantage of the same performance and HTML5 technologies available in the Google Chrome Web browser.\n\nSee the project [README.md](https://github.com/chromiumembedded/cef/blob/master/README.md) for additional introductory material.\n\n# Dependencies\n\nThe CEF project depends on a number of other projects maintained by third parties. The major projects that CEF depends on are:\n\n  * [Chromium](http://www.chromium.org/Home) - Provides general functionality like network stack, threading, message loop, logging and process control needed to create a fully functional Web browser. Implements \"platform\" code that allows Blink to communicate with V8 and Skia. Many Chromium design documents can be found at http://dev.chromium.org/developers.\n  * [Blink](https://www.chromium.org/blink) (formerly WebKit) - The rendering implementation used by Chromium. Provides DOM parsing, layout, event handling, rendering and HTML5 JavaScript APIs. Some HTML5 implementations are split between the Blink and Chromium code bases.\n  * [V8](https://developers.google.com/v8/) - JavaScript engine.\n  * [Skia](https://skia.org/) - 2D graphics library used for rendering non-accelerated content. More information on how Chromium integrates Skia is available [here](http://www.chromium.org/developers/design-documents/graphics-and-skia).\n  * [Angle](https://chromium.googlesource.com/angle/angle/+/master/README.md) - 3D graphics translation layer for Windows that converts GLES calls to DirectX. More information about accelerated compositing is available [here](http://dev.chromium.org/developers/design-documents/gpu-accelerated-compositing-in-chrome).\n\n# Versions\n\nThere have been three versions of CEF to date.\n\n  * CEF1 - Single process implementation using the Chromium WebKit API (now discontinued).\n  * CEF2 - Multi process implementation built on the Chromium browser (now discontinued).\n  * CEF3 - Multi process implementation using either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\").\n\nOnly the CEF3 version is currently developed and supported. See the \"History\" and \"Modern Architecture\" sections below for background and the [Branches And Building](branches_and_building.md) page for current development information.\n\n# History\n\nIn 2008, when the CEF project started, Chromium was a monolithic application built on top of Apple's [WebKit](https://webkit.org/) rendering engine. Google maintained an in-tree variant of WebKit (called the [Chromium WebKit API](https://www.youtube.com/watch?v=JFzC_Gx76E8)) that added additional functionality specific to Chromium. The first version of CEF (called CEF1) was implemented on top of this Chromium WebKit API and used the default single-process application model supported by WebKit1 at that time (for more details on CEF1 architecture see the \"CEF1\" section below).\n\nUse of the Chromium WebKit API came with some known limitations. For example, that API layer did not support the multi-process model that was the basis for most of Google Chrome's [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md). It also lacked many of the UI features that were becoming necessary to support new web platform features (like device selection dialogs, permissions management, etc). We therefore began a new effort, in 2010, to reimplement CEF (called CEF2) on top of the fully-featured but monolithic Chromium browser UI. The lack of internal API boundaries in the Chromium code at that time made it necessary for us to take an \"all or nothing\" approach. If we could create a CEF browser window based on the complete Chrome UI we would effectively gain access to all of Chrome's capabilities \"for free\" (for more details on CEF2 architecture see the \"CEF2\" section below).\n\nGoogle began acknowledging the validity of the embedded use case for Chromium in 2010 and started work on new internal API boundaries to make embedding easier. The [Chromium Content API](http://www.chromium.org/developers/content-module/content-api), which encapsulated the multi-process application model and provided stub implementations for most web platform features, reached a development stage in late 2011 where it was a viable option for Chromium embedders like CEF. It still didn't provide all of the features that we might like, but it was a \"supported\" API layer. We therefore abandoned the CEF2 effort in early 2012 and focused our efforts instead on the Content API as the more viable embedding option. The existing CEF1 API, which was strongly dependent on WebKit1 and the single-process model, could not be directly ported to the Content API. A new CEF API (called CEF3), with substantial breaking API changes and multi-process support, was released in early 2013 (for more details on CEF3 architecture see the \"Modern Architecture\" and \"CEF3\" sections below).\n\nAlso in 2013, Google decided to [fork the WebKit project](https://blog.chromium.org/2013/04/blink-rendering-engine-for-chromium.html). After renaming it to Blink they removed many of the API boundaries that had previously existed between Chromium and WebKit and effectively deleted the Chromium WebKit API. The multi-process architecture, which was optional in WebKit1, was now a requirement with Chromium/Blink. CEF1, which depended on the Chromium WebKit API, no longer had a viable future and CEF3 became the only path forward.\n\nFast forward another 7 years, to 2020, and the Chromium architecture has again changed substantially. A lot of effort has been spent to define clear architectural layers (sometimes called [components](https://www.chromium.org/developers/design-documents/cookbook/)) in the Chromium/Blink source code. New platforms and new embedders have entered the Chromium ecosystem. And yet, many features desired by CEF users remain stubbornly out of reach in the Chrome UI layer. With this new, more modern, version of Chromium, we decided it was time to revisit our goals from CEF2 and create a new CEF version based on the Chrome UI layer (now called the \"Chrome runtime\" in CEF3). Continue to the \"Modern Architecture\" section for details.\n\n# Modern Architecture\n\nThe modern Chromium code base is composed of architectural layers, with the primary application layers being \"content\" (for the [Content API](http://www.chromium.org/developers/content-module/content-api)) and \"chrome\" (for the Chrome UI layer). The \"content\" layer includes [WebContents](https://source.chromium.org/chromium/chromium/src/+/master:content/public/browser/web_contents.h) as the primary browser object and provides implementations for most of the generic web platform and application/process management functionality. The \"chrome\" layer includes [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) as the primary browser object and provides implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc.\n\nFor historical reasons (outlined above), CEF browser windows have been based on the \"content\" layer WebContents object since the introduction of CEF3 in 2013. Adding support for additional \"chrome\" layer features in that architecture was a serious effort because it involved careful understanding and cherry-picking of the related functionality from \"chrome\" code into the CEF code base. Over time we have added dependencies on the \"chrome\" layer targets to support some features in CEF (such and extensions, PDF viewer and print preview) and to avoid code duplication. As a result, CEF3 binaries in modern times already contained most/all of the code that would be required to launch a stand-alone \"chrome\" Browser window, but simply lacked the mechanism to do so.\n\nIn 2020 we launched a [new effort](https://github.com/chromiumembedded/cef/issues/2969) to implement the CEF3 API on top of a fully-featured \"chrome\" Browser window. To be usable in existing CEF3 client applications the \"chrome\" window needed to support a large subset of CEF3's existing callbacks/intercepts (e.g. loading progress, network requests, etc.), and be inserted into the existing [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) structure. At the same time, it was necessary to substantially refactor the internal CEF (libcef) code to extract functionality that was common to both the old WebContents-based approach and the new Browser-based approach. As part of this refactoring we renamed the existing \"content\" layer implementation to the \"Alloy runtime\" (where Alloy = Chrome + other stuff) and named the new \"chrome\" layer implementation as the \"Chrome runtime\". Proceed to the \"CEF3\" section below for additional feature and implementation details.\n\n# Common API Usage\n\nAll versions of CEF expose a simple, easy-to-use API designed to insulate users from the underlying Chromium and Blink code complexity. Common usage is as follows:\n\n1. Initialize CEF by calling CefInitialize().\n\n2. Perform work on the UI message loop by calling CefRunMessageLoop() or CefDoMessageLoopWork().\n\n3. Create a browser window by calling CreateBrowser() or CreateBrowserSync() and passing in a CefClient instance.\n\n4. Shut down CEF by calling CefShutdown() before the application exits.\n\n# C Wrapper API\n\nThe libcef shared library exports a C API that isolates the user from the CEF runtime and code base. The libcef\\_dll\\_wrapper project, which is distributed in source code form as part of the binary release, wraps this exported C API in a C++ API that is then linked into the client application. The code for this C/C++ API translation layer is automatically generated by the [translator](https://github.com/chromiumembedded/cef/blob/master/tools/translator.README.txt) tool. Direct usage of the C API is described on the [Using The CAPI](using_the_capi.md) page.\n\n# CEF1 (Discontinued)\n\nCEF1 was the initial version of CEF first released in 2008. It was discontinued in 2013 when Google forked the WebKit project and subsequently deleted the Chromium WebKit API. See the \"History\" section above for additional details.\n\nThe single process architecture used by CEF1 integrates Chromium and WebKit directly into the client application. Advantages to the single process architecture included reduced memory usage and closer integration with the client application. For example, having the renderer running in the same process allowed JavaScript bindings to synchronously communicate between client code and renderer code. Disadvantages included [reduced performance](https://github.com/chromiumembedded/cef/issues/304) with certain types of accelerated content, [crashes](https://github.com/chromiumembedded/cef/issues/242) due to plugins like Flash running in the same process, and lack of support for application [security and stability features](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md) that required a multi-process architecture.\n\n## API Usage\n\nBelow is an overview of the main CEF1 interfaces and their uses. Since CEF1 is discontinued we no longer provide detailed usage information.\n\n  * [CefApp](http://magpcss.org/ceforum/apidocs/projects/(default)/CefApp.html) - This interface is passed to CefInitialize() and allows the application to customize global functionality like resource loading and proxy handling.\n  * [CefClient](http://magpcss.org/ceforum/apidocs/projects/(default)/CefClient.html) - This interface is passed to CefCreateBrowser() or CefCreateBrowserSync() and acts as the connection between an individual CEF browser instance and the client application. Additional interfaces for request handling, display handling, etc. are exposed via this interface.\n  * [CefBrowser](http://magpcss.org/ceforum/apidocs/projects/(default)/CefBrowser.html) - Exposes capabilities provided by the browser. This includes back/forward navigation, source retrieval, request loading, etc. A single CefBrowser may have one or more child [CefFrame](http://magpcss.org/ceforum/apidocs/projects/(default)/CefFrame.html) objects.\n\n## Threading Considerations\n\nCEF1 includes UI, IO and FILE threads. The UI thread creates browser windows and is used for all interaction with WebKit and V8. The IO thread is used for handling schema and network requests. The FILE thread is used for the application cache and other miscellaneous activities.\n\nWhen using CEF1 you should keep the following threading considerations in mind:\n\n  * Do not perform blocking operations on the UI thread. This can lead to serious performance issues.\n  * The UI thread will be the same as the main application thread if CefInitialize() is called with a CefSettings.multi\\_threaded\\_message\\_loop value of false.\n  * All WebKit and V8 interation must take place on the UI thread. Consequently, some CEF API functions can only be called on the UI thread. Functions that have this limitation will be documented accordingly in the associated CEF header file.\n  * The [CefPostTask](http://magpcss.org/ceforum/apidocs/projects/(default)/(_globals).html#CefPostTask(CefThreadId,CefRefPtr<CefTask>)) method can be used to post tasks asnychronously between the various threads.\n\n## Implementation Details\n\nCEF1 has the following major implementation classes:\n\n  * CefContext - Represents the global CEF context. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * CefProcess - Used by CefContext to create and manage the CEF threads.\n  * BrowserWebKitInit - Manages the global WebKit environment as exposed by the Chromium WebKit API.\n  * WebViewHost - Provides the native window \"wrapper\" implementation for a WebView. This class extends WebWidgetHost which provides functionality shared in common with popup widgets (like select menus) on some platforms.\n  * CefBrowserImpl - Implements the CefBrowser interface, creates the WebViewHost and provides the glue code for a single browser instance.\n  * BrowserWebViewDelegate - Implements the WebKit interfaces that provide communication between CefBrowserImpl and the underlying WebView.\n\n# CEF2 (Discontinued)\n\nCEF2 was an effort to reimplement the CEF1 API on top of the Chrome browser UI as it existed in 2010. CEF2 was discontinued when Chromium announced support for the Content API. Information about CEF2 can be found in the \"History\" section above and [here](http://magpcss.org/ceforum/viewtopic.php?f=10&t=122) on the CEF Forum.\n\n# CEF3\n\nCEF3 has been the recommended and supported version of CEF since January 2013. It uses the same multi process architecture as the Chromium Web browser via either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\"). This architecture provides a number of advantages over the single process architecture used by CEF1:\n\n  * Support for multi-process run mode (with related [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md)).\n  * More code sharing with the Chromium browser.\n  * Improved performance and less breakage due to use of the \"supported\" code path.\n  * Faster access to new features.\n\nIn most cases CEF3 will have the same performance and stability characteristics as the Chromium Web browser. Both the Alloy runtime and the Chrome runtime support modern web platform features and provide the safety/security expected from an up-to-date Chromium-based browser. The Chrome runtime, which was introduced in 2020, adds implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc. At the time of writing, the Chrome runtime requires use of the [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) in CEF client applications and does not support off-screen rendering. A current list of open issues specific to the Chrome runtime can be found [here](https://github.com/chromiumembedded/cef/issues?q=is%3Aissue+is%3Aopen+label%3Achrome).\n\nStarting with the M125 release (mid-2024) the Alloy runtime has been [split](https://github.com/chromiumembedded/cef/issues/3681) into separate style and bootstrap components. Both Chrome style and Alloy style browsers/windows can now be created while using the Chrome bootstrap. The Alloy bootstrap has been [removed](https://github.com/chromiumembedded/cef/issues/3685) starting with the M128 release.\n\n## API Usage\n\nSee the [General Usage](general_usage.md) page for detailed API usage instructions.\n\n## Process Considerations\n\nSee the [Processes](general_usage.md#processes) section of the [General Usage](general_usage.md) page for details.\n\n## Threading Considerations\n\nSee the [Threads](general_usage.md#threads) section of the [General Usage](general_usage.md) page for details.\n\n## Implementation Details\n\nFor an implementation overview see the \"Modern Architecture\" section above. \n\nShared CEF library/runtime classes use the Cef prefix. Classes that implement the Alloy or Chrome runtime use the Alloy or Chrome prefixes respectively. Classes that extend an existing Chrome-prefixed class add the Cef or Alloy suffix, thereby following the existing naming pattern of Chrome-derived classes.\n\n### Alloy Runtime Classes\n\nAlloy runtime bootstrap was [removed](https://github.com/chromiumembedded/cef/issues/3685) in M128 (mid-2024) and Alloy runtime style is now supported using the Chrome runtime bootstrap. Alloy runtime style is based on the \"content\" layer and has the following major implementation classes:\n\n  * [AlloyBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/alloy/alloy_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n\n### Chrome Runtime Classes\n\nChrome runtime bootstrap and style is based on the \"chrome\" layer and has the following major implementation classes:\n\n  * [ChromeMainDelegateCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_main_delegate_cef.h) - Implements the common process bootstrap logic.\n  * [ChromeContentClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_content_client_cef.h) - Implements the Content API callbacks that are common to all processes.\n  * [CefContext](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/context.h) - Represents the global CEF context in the browser process. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * [ChromeBrowserMainExtraPartsCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_main_extra_parts_cef.h) - Implements the browser process bootstrap logic.\n  * [ChromeContentBrowserClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_content_browser_client_cef.h) - Implements the Content API callbacks for the browser process.\n  * [ChromeBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n  * [ChromeContentRendererClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/chrome/chrome_content_renderer_client_cef.h) - Implements the Content API callbacks for the render process.\n  * [CefBrowserImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/browser_impl.h) - Implements the CefBrowser interface in the render process. Provides the glue code and implements interfaces for communicating with the RenderView.\n  * [ChromeBrowserDelegate](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_delegate.h) - Interface injected into Chrome's [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) object (via [patch files](https://github.com/chromiumembedded/cef/blob/master/patch/README.txt)) to support callbacks into CEF code.\n  * [ChromeBrowserFrame](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h) - Widget for a Views-hosted Chrome browser.\n\nAn overview of the Chrome Browser object model is also available [here](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h).","tools/AGENTS.md":"# CEF Tools Contributor and Agent Guidelines\n\nThis file applies to `//cef/tools` and its descendants.\n\n## Generator inventory and coverage\n\n- Every direct-child, non-test `make_*.py` generator must have a matching\n  `make_*_test.py` module.\n- `make_generator_inventory_test.py` enforces the direct-child inventory. When\n  adding or removing a generator, update its expected count intentionally and\n  keep nested generators, helpers, and existing tests out of the inventory.\n- Exercise every top-level generator function through at least one successful\n  test. Cover meaningful explicit error branches, writer behavior, and the\n  generator's CLI style; do not treat filename coverage as function coverage.\n- Use standard-library `unittest`, `tempfile`, and `unittest.mock`. Run from the\n  CEF root:\n\n  ```sh\n  python3 -m unittest discover -s tools -p '*_test.py'\n  python3 -m unittest discover -s tools -p 'make_example_test.py' -v\n  ```\n\n- Run the complete suite twice for generator-wide work. These modules share\n  parser state, so the second run detects ordering and cleanup leaks.\n\n## Hermetic fixtures and goldens\n\n- Put deterministic inputs and reviewed goldens under\n  `tools/testdata/make_generators/`; use `generator_test_util.py` for shared\n  fixture, manifest, archive, and CLI helpers.\n- Mock or fix time, year, Git metadata, versions, platforms, environment\n  variables, external commands, and formatter results when they affect output.\n- Goldens must originate from a reviewed baseline, never from ignored\n  working-tree output, and tests must not contain an auto-update path.\n- Use inline expectations for small output and reviewed full-file goldens for\n  larger generated C/C++ content. Add targeted assertions that explain the\n  behavior protected by a golden.\n- Prove that customized CppToC/CToCpp bodies survive regeneration, source\n  fixtures are not modified, and relevant paths work when they contain spaces.\n\n## Writer contracts\n\n- Test every writer on its first generation and an identical second\n  generation.\n- For `write_file_if_changed`, assert changed/unchanged returns and preserved\n  mtime. For unconditional writers, assert stable bytes across rewrites.\n- Multi-output writers must report a change when any output changes. Test\n  repairs where only one output was corrupted.\n- Pre-publication failures must leave outputs missing or unchanged. Characterize\n  partial I/O-failure output before changing it; atomic publication is a\n  separate behavior change.\n\n## CLI contracts\n\n- Cover invalid status, stdout, stderr, and partial artifacts, plus successful\n  stdout, single-file, multi-output, argparse, and distribution CLI styles.\n- If a generator function returns metadata with its content, such as\n  `(content, customized)`, unpack the result at the CLI boundary and write only\n  the string content. Do not change the underlying generator return contract\n  merely to fix a CLI.\n- Assert progress messages exactly when callers may depend on them, and return\n  explicit nonzero statuses for rejected invocations.\n\n## Parser and module state\n\n- Restore parser notification context and other module globals with\n  `try/finally`; add test cleanup so failing regressions cannot leak state.\n- Generator modules intended for reuse must be importable without parsing\n  arguments, exiting, mutating files, calling Git, or launching subprocesses.\n  Put orchestration in `main(argv=None)` and use a conventional guarded entry\n  point when refactoring for importability.\n\n## Output equivalence\n\n- Establish an exact pre-refactor baseline and keep testability refactors\n  separate from behavior fixes.\n- Testability refactors must preserve generated bytes, paths, ordering,\n  comments, whitespace, guards, encoding, newlines, modes, and symlink targets.\n- Compare fixes to the latest approved baseline while retaining the original\n  refactor baseline as an immutable reference.\n- Return-value, status, diagnostic, and CLI changes must not alter generated\n  files unless that is their documented purpose.\n- For translator changes, run a repository-scale comparison covering C API,\n  CppToC, CToCpp, wrapper, dylib, and GYPI outputs.\n- For distribution changes, compare the complete normalized tree. Compare\n  archive member paths, types, uncompressed bytes, and modes; normalize archive\n  timestamps only. Do not use raw archive-container hashes as equivalence.\n- Use the same Python interpreter as the recorded baseline. Python-version\n  differences can change comment wrapping and produce misleading byte deltas.\n\n## Bug-fix workflow\n\n- Reproduce a bug with a focused regression before changing production code.\n- Keep coverage/refactor checkpoints separate from behavior fixes so output\n  differences cannot be attributed to the wrong change.\n- Keep unrelated bugs independently reviewable. Closely related instances of\n  the same root cause may be grouped when explicitly requested.\n\n## Formatting and validation\n\n- From the CEF root, format only explicit changed Python paths:\n\n  ```sh\n  python3 tools/fix_style.py tools/make_example.py tools/make_example_test.py\n  ```\n\n- Inspect formatter output immediately. The formatter may rewrap unrelated\n  legacy code; revert that churn with targeted patches.\n- Compile every changed generator, helper, and test.\n- Run `git diff --check` and scan untracked files for trailing whitespace.\n- Re-run focused tests after formatting, then run the complete suite twice.\n","tools/CLAUDE.md":"@AGENTS.md\n","tools/cefbuilds/README.md":"# CEF Builds JSON Tools\n\nTools for generating and maintaining the JSON index files used by the\n[CEF Builds](https://cef-builds.spotifycdn.com/index.html) CDN and the CEF\ninstaller.\n\n## Files\n\n### Core libraries\n\n- **`cef_json_builder.py`** — Builds and maintains the master `index.json` file\n  that contains the full catalog of CEF binary distributions across all\n  platforms, versions, and channels. Handles file metadata (name, size, sha1,\n  last_modified), Chromium version mapping, and sandbox compatibility hashes.\n\n- **`cef_installer_builder.py`** — Generates installer-optimized CDN query files\n  from a populated `cef_json_builder` instance. Produces lightweight JSON files\n  designed for efficient HTTP HEAD timestamp checks by the CEF installer.\n\n### Data files\n\n- **`revoked.json`** — Manually maintained list of revoked CEF versions. Revoked\n  versions are excluded from all installer-generated JSON output. The installer\n  also fetches this file from the CDN and refuses to install any listed version.\n\n### Examples and tests\n\n- **`cef_json_builder_example.py`** — Example script demonstrating\n  `cef_json_builder` usage. Creates and updates a local `index.json` with fake\n  file data.\n\n- **`cef_json_builder_test.py`** — Unit tests for `cef_json_builder`.\n\n- **`cef_installer_builder_test.py`** — Unit tests for `cef_installer_builder`.\n\n## CDN file formats\n\n### Master index\n\n- **`index.json`** — Full data index of all CEF binary distributions. Generated\n  by `cef_json_builder`. Keyed by platform, with version records sorted\n  newest-first by file last_modified timestamp.\n\n### Installer query files\n\nGenerated by `cef_installer_builder` from the master index:\n\n- **`stable.txt`** — Current stable milestone number (e.g., `137`).\n\n- **`{milestone}.json`** (e.g., `137.json`) — Newest build per platform for a\n  given milestone. Used by the installer to check if an update is available.\n\n- **`{milestone}_{platform}.json`** (e.g., `137_windows64.json`) — All builds\n  for a milestone+platform combination, sorted newest-first.\n\n- **`{abi_hash}_{platform}.json`** (e.g., `abc123def4567890_windows64.json`) —\n  All builds compatible with a given ABI hash and platform across all milestones,\n  sorted newest-first. Windows platforms only (tied to `chrome_elf.dll` /\n  Chromium sandbox ABI).\n\n## Concepts\n\n### Platforms\n\nSupported platforms: `linux32`, `linux64`, `linuxarm`, `linuxarm64`,\n`macosarm64`, `macosx64`, `windows32`, `windows64`, `windowsarm64`.\n\n### Distribution types\n\nEach version may have files of these types: `standard`, `minimal`, `client`,\n`tools`, `release_symbols`, `debug_symbols`, `signed`.\n\nThe `signed` type contains code-signed archives with catalog files, used by the\ninstaller for verified installation.\n\n### Channels\n\nVersions belong to either the `stable` or `beta` channel.\n\n### Version formats\n\n- **New-style**: `137.3.5+g62d140e+chromium-137.0.7204.6`\n  - Short version: `137.3.5` (everything before the first `+`)\n  - Milestone: `137` (major version number)\n- **Old-style**: `3.2704.1414.g185cd6c` (predates the installer format)\n\n### ABI hash (`sandbox_compat`)\n\nA 16-character hex string identifying the Windows sandbox ABI compatibility\nlevel. Derived from `cef_api_versions.json` on GitHub. Versions sharing the same\nABI hash can use the same `chrome_elf.dll` and are interchangeable from the\nsandbox's perspective.\n\n### Revocation\n\nThe `revoked.json` file lists versions that must not be installed. When passed\nto `cef_installer_builder`, revoked versions are automatically excluded from\nall generated output. The installer also fetches this file from the CDN at\nruntime and refuses to install any listed version.\n\nEntries can revoke a single version or a range of versions:\n\n```json\n{\n  \"revoked_versions\": [\n    {\n      \"version\": \"137.1.0\",\n      \"reason\": \"CVE-2024-XXXXX: critical sandbox escape\",\n      \"revoked_at\": \"2024-01-15T00:00:00Z\"\n    },\n    {\n      \"version_min\": \"138.0.0\",\n      \"version_max\": \"138.2.99\",\n      \"reason\": \"CVE-2024-YYYYY: affects all 138.0–138.2 builds\",\n      \"revoked_at\": \"2024-02-01T00:00:00Z\"\n    }\n  ]\n}\n```\n\n**Single version** (point revocation):\n- `version` — Short version string (e.g., `137.1.0`).\n\n**Version range** (inclusive):\n- `version_min` — Inclusive lower bound (e.g., `138.0.0`).\n- `version_max` — Inclusive upper bound (e.g., `138.2.99`).\n\n**Common fields:**\n- `reason` — Human-readable explanation (CVE ID, bug reference, etc.).\n- `revoked_at` — ISO 8601 timestamp of when the revocation was added.\n\nA single-version entry using `version` is equivalent to setting both\n`version_min` and `version_max` to the same value. If both `version` and\n`version_min`/`version_max` are present, the range fields take precedence.\n\n## Running tests\n\n```bash\ncd cef/tools/cefbuilds\npython3 -m unittest cef_json_builder_test -v\npython3 -m unittest cef_installer_builder_test -v\n```\n","tools/clang/CLAUDE.md":"# CEF Clang Tools - Claude Code Instructions\n\nThis file provides guidance to Claude Code when working with CEF clang tools.\n\n## Overview\n\nThe `cef_cpp_rewriter` tool is a clang AST-based rewriter for C++20 modernization.\nIt uses Clang's LibTooling and AST matchers to perform type-aware transformations\nthat cannot be done with simple regex.\n\n**Supported transformations:** `.contains()`, structured bindings, iterator loops,\nDISALLOW_COPY_AND_ASSIGN. See [TRANSFORMS.md](TRANSFORMS.md) for complete documentation.\n\n**Important:** CEF is a separate git repository within chromium/src. Chromium's\nclang tool scripts use git commands that don't work across repository boundaries.\nUse the CEF-specific scripts in `cef/tools/clang/scripts/` instead.\n\n## Key Files\n\n- `cef/tools/clang/cef_cpp_rewriter/CefCppRewriter.cpp` - Main tool implementation\n- `cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt` - Build configuration\n- `cef/tools/clang/scripts/build_clang_rewriter.sh` - Bootstrap script\n- `cef/tools/clang/scripts/package_standalone.sh` - Package for standalone use\n- `cef/tools/clang/standalone/` - Standalone distribution files\n- `cef/tools/clang/cef_cpp_rewriter/tests/` - Test cases\n\n## Prerequisites\n\n**Python 3.10+ required.** Chromium's build scripts use type union syntax that requires Python 3.10+. On macOS:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\n```\n\n## Development Workflow\n\n### Building the Tool\n\nAfter modifying `CefCppRewriter.cpp`:\n\n```bash\n# Fast incremental rebuild (~seconds)\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Never re-run `build_clang_rewriter.sh`** unless the build directory was deleted.\nIt rebuilds clang from scratch (~30 minutes).\n\n### Testing Matchers with clang-query\n\n```bash\nexport PATH=$PATH:third_party/llvm-build/Release+Asserts/bin\nclang-query /tmp/test.cc --\n```\n\n### Generating compile_commands.json for Manual Testing\n\nThe `test_tool.py` script generates this automatically, but for manual testing:\n\n```bash\n# macOS (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -isysroot $(xcrun --show-sdk-path) -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Linux (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Run the tool (--disable-path-filter needed for test files)\nthird_party/llvm-build/Release+Asserts/bin/cef_cpp_rewriter \\\n  --disable-path-filter -p $TEST_DIR $TEST_DIR/contains-original.cc\n```\n\n### Running Tests\n\n```bash\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n### Debugging\n\n1. Add `dumpColor()` calls in `run()` to visualize matched AST nodes\n2. Return 1 from `main()` to see tool output (run_tool.py hides output on success)\n3. Dump AST: `clang++ -Xclang -ast-dump -std=c++20 file.cc`\n\n## Important Constraints\n\n1. **Symlink required**: The tool must be symlinked to `tools/clang/cef_cpp_rewriter`\n2. **Do not transform std::string**: Only associative containers have C++20 `.contains()`\n3. **Same container check**: Verify `find()` and `end()` are called on the same object\n4. **Skip macros**: Don't transform code inside macro expansions\n5. **CEF paths only**: Only transform files containing `/cef/` in their path\n\n## Compatibility Requirements\n\nCEF targets C++20. All transformations must work with these minimum toolchain versions:\n\n- GCC 10 (CEF minimum)\n- macOS 12.0 deployment target\n\nFeatures to AVOID (incompatible):\n\n- `std::string::contains()` - C++23, needs GCC 11+\n- `std::format` - needs GCC 13+ and macOS 13.3+\n- `using enum` - needs GCC 11+\n\n## Adding New Transformations\n\n### Quick Steps\n\n1. Add a command-line flag in `CefCppRewriter.cpp`:\n    ```cpp\n    static llvm::cl::opt<bool> EnableNewFeature(\"new-feature\",\n        llvm::cl::desc(\"Enable new feature transformation\"),\n        llvm::cl::init(true));\n    ```\n\n2. Create a new `MatchCallback` class for the transformation\n\n3. Add matcher to `match_finder` in `main()` guarded by the flag\n\n4. Add test files: `tests/newfeature-original.cc` and `tests/newfeature-expected.cc`\n\n5. Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n   (test_tool.py generates compile_commands.json automatically)\n\n### Full Implementation Checklist Template\n\nUse this checklist when implementing any new transformation:\n\n```markdown\n### Phase N: [Transformation Name]\n**Priority:** Nth | **Complexity:** Low/Medium/High | **Compat:** GCC X+\n\n[Brief description of the transformation]\n\n**Before/After Example:**\n```cpp\n// Before\n[old code pattern]\n\n// After\n[new code pattern]\n```\n\n**Checklist:**\n- [ ] Verify compatibility with GCC 10 and macOS 12.0 deployment target\n- [ ] Add `--flag-name` command-line flag (default: true/false)\n- [ ] Implement `TransformNameRewriter` class with:\n  - [ ] `run()` method that handles matched nodes\n  - [ ] Macro expansion filtering (`isMacroID()`, `isMacroBodyExpansion()`)\n  - [ ] System header filtering (`isInSystemHeader()`)\n  - [ ] Path filtering (skip non-CEF files unless `--disable-path-filter`)\n  - [ ] Deduplication via `processed_locations_` set\n- [ ] Create AST matcher(s) - test with `clang-query` first\n- [ ] Add matcher to `match_finder` in `main()` guarded by flag\n- [ ] Create test files: `transform-name-original.cc`, `transform-name-expected.cc`\n- [ ] Create negative test cases: `transform-name-negative-original.cc` (copy to `-expected.cc`)\n- [ ] Rebuild tool: `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n- [ ] Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n- [ ] Run on CEF code: `python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool --tool-args=\"--flag-name\" cef/libcef cef/libcef_dll cef/tests`\n- [ ] Review diffs and verify correctness\n- [ ] Build CEF to verify no compile errors\n- [ ] Run CEF tests to verify no regressions\n- [ ] Search for skipped instances (macros, edge cases) using grep\n- [ ] Manually transform skipped instances if appropriate\n- [ ] Update TRANSFORMS.md with transformation details\n- [ ] Update CLAUDE.md tool arguments table\n- [ ] Update README.md tool arguments table and transformations list\n```\n\n### Rewriter Class Template\n\n```cpp\nclass NewFeatureRewriter : public MatchFinder::MatchCallback {\n public:\n  explicit NewFeatureRewriter(OutputHelper* output) : output_helper_(*output) {}\n\n  void reset() { processed_locations_.clear(); }\n\n  void run(const MatchFinder::MatchResult& result) override {\n    const auto* matched_node = result.Nodes.getNodeAs<NodeType>(\"bindingName\");\n    if (!matched_node) return;\n\n    const SourceManager& sm = *result.SourceManager;\n    const LangOptions& opts = result.Context->getLangOpts();\n\n    // Skip macros\n    if (matched_node->getBeginLoc().isMacroID() ||\n        sm.isMacroBodyExpansion(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Skip system headers\n    if (sm.isInSystemHeader(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Deduplicate\n    unsigned offset = sm.getFileOffset(matched_node->getBeginLoc());\n    if (processed_locations_.count(offset)) return;\n\n    // Path filter\n    if (!DisablePathFilter) {\n      StringRef filename = sm.getFilename(matched_node->getBeginLoc());\n      if (!filename.contains(\"/cef/\")) return;\n    }\n\n    processed_locations_.insert(offset);\n\n    // Generate replacement\n    std::string replacement = /* ... */;\n    CharSourceRange range = CharSourceRange::getTokenRange(\n        matched_node->getSourceRange());\n    output_helper_.Replace(range, replacement, sm, opts);\n  }\n\n private:\n  OutputHelper& output_helper_;\n  std::set<unsigned> processed_locations_;\n};\n```\n\n### Common Pitfalls\n\n1. **Iterator comparisons use overloaded operators**: Use `cxxOperatorCallExpr(hasOverloadedOperatorName(\"!=\"))` not `binaryOperator`\n2. **Integer literals need implicit cast handling**: Use `ignoringImpCasts(integerLiteral(...))`\n3. **Pointer access needs separate matching**: Include `hasType(pointsTo(...))` in an `anyOf()`\n4. **Token vs char ranges**: `getTokenRange()` includes full last token, `getCharRange()` is exact\n5. **Don't transform std::string methods**: Many string methods have same names but different semantics\n\n## Running the Tool on CEF Code\n\n```bash\n# Create build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool && cp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run all transformations (default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--contains=false --structured-bindings\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\nExample: `--tool-args=\"--only=iterator-loops\"` runs only the iterator-loops transformation.\n\n## Critical Reminders\n\n1. **Symlink required**: `test_tool.py` looks for tools in `tools/clang/`, so the symlink must exist\n2. **Test naming**: Files must be named `*-original.cc` and `*-expected.cc` (not `-test.cc`)\n3. **Do not transform `std::string::find()`**: Only associative containers have C++20 `.contains()`\n4. **Incremental builds**: Use `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n5. **Do not re-run build.py**: It deletes everything and rebuilds from scratch (~30 min)\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory (from chromium/src)\n./cef/tools/clang/scripts/package_standalone.sh /path/to/cpp_rewriter\n\n# This creates a self-contained distribution:\n# /path/to/cpp_rewriter/\n# ├── bin/cpp_rewriter           # The tool binary (renamed from cef_cpp_rewriter)\n# ├── lib/clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper (auto-detects resource dir)\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\n**Key differences from CEF usage:**\n\n- Uses `--path-filter` for substring matching instead of default `/cef/` filter\n- Bundled clang headers allow tool to work without matching system clang\n- No `--generate-compdb` - requires pre-existing `compile_commands.json`\n- `CMAKE_EXPORT_COMPILE_COMMANDS` only works with Ninja/Makefiles generators (not Xcode/VS)\n\nSee `standalone/README.md` for complete standalone usage documentation.\n","tools/clang/README.md":"# CEF Clang Tools\n\nThis directory contains clang-based tools for CEF code modernization and refactoring.\n\n## Tools\n\n### cef_cpp_rewriter\n\nA clang AST-based rewriter tool for automating C++20 modernization of CEF code.\n\n**Supported transformations:**\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for complete documentation of all transformations, command-line flags, and examples.\n\n## Prerequisites\n\n- Chromium checkout with CEF\n- **Python 3.10+** (Chromium's build scripts require it)\n- ~30 minutes for initial clang bootstrap\n\n**Note:** CEF is a separate git repository within chromium/src. Chromium's clang\ntool scripts (`run_tool.py`, `test_tool.py`, `apply_edits.py`) use git commands\nthat don't work across repository boundaries. This directory provides CEF-specific\nreplacements: `run_tool.py`, `test_tool.py`, and `apply_edits.py`.\n\n### Python Version\n\nmacOS ships with Python 3.9 which is too old. Install Python 3.12 via Homebrew:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\npython3 --version  # Should show 3.12.x\n```\n\nAdd the export line to `~/.zshrc` to make it permanent.\n\n## Quick Start\n\n### Initial Setup (one-time, ~30 minutes)\n\n```bash\n# From chromium/src directory\n./cef/tools/clang/scripts/build_clang_rewriter.sh\n```\n\nThis will:\n\n1. Create a symlink from `tools/clang/cef_cpp_rewriter` to the CEF tool\n2. Bootstrap clang with the tool (~30 minutes)\n\n**Warning:** The clang bootstrap updates `third_party/llvm-build/`, which will\ninvalidate all existing Chromium/CEF build directories and trigger a full\nrebuild the next time you build. Plan accordingly.\n\n### Running the Tool\n\n```bash\n# Create a build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool\ncp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run the tool on CEF code (all transformations enabled by default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--structured-bindings --contains=false\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Or run on all CEF files (omit path arguments)\n# python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool\n\n# Process and apply the edits\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\n**Examples:**\n```bash\n# Run only iterator-loops transformation\n--tool-args=\"--only=iterator-loops\"\n\n# Run only contains and structured-bindings\n--tool-args=\"--only=contains,structured-bindings\"\n\n# Disable specific transformation (all others still run)\n--tool-args=\"--contains=false\"\n```\n\n### Incremental Rebuilds\n\nAfter modifying `CefCppRewriter.cpp`, rebuild quickly with:\n\n```bash\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Do not re-run `build_clang_rewriter.sh`** - it rebuilds everything from scratch.\n\n## Testing\n\n```bash\n# Run tool tests\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n## Compatibility\n\nCEF targets C++20. See [TRANSFORMS.md](TRANSFORMS.md) for minimum toolchain versions.\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory\n./cef/tools/clang/scripts/package_standalone.sh /path/to/target\n\n# This creates:\n# /path/to/target/\n# ├── bin/cpp_rewriter           # The tool binary\n# ├── lib/clang/<version>/       # Bundled clang headers\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\nThe standalone distribution is self-contained and includes bundled clang headers\nso it works without requiring a matching system clang installation.\n\n**Usage on any CMake project:**\n```bash\ncd my-project\n\n# Generate compile_commands.json (requires Ninja or Makefiles generator)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Run the rewriter\n/path/to/target/scripts/run_rewriter.py -p build src/ \\\n  | /path/to/target/scripts/apply_edits.py --base-dir build\n```\n\nSee `standalone/README.md` for complete standalone usage documentation.\n\n## Directory Structure\n\n```\ncef/tools/clang/\n├── cef_cpp_rewriter/\n│   ├── CMakeLists.txt\n│   ├── CefCppRewriter.cpp\n│   ├── OutputHelper.h\n│   ├── OutputHelper.cpp\n│   └── tests/\n│       ├── contains-original.cc\n│       ├── contains-expected.cc\n│       ├── contains-negative-original.cc\n│       ├── contains-negative-expected.cc\n│       ├── disallow-copy-original.cc\n│       ├── disallow-copy-expected.cc\n│       ├── disallow-copy-negative-original.cc\n│       ├── disallow-copy-negative-expected.cc\n│       ├── structured-bindings-original.cc\n│       ├── structured-bindings-expected.cc\n│       ├── structured-bindings-negative-original.cc\n│       ├── structured-bindings-negative-expected.cc\n│       ├── iterator-loops-original.cc\n│       ├── iterator-loops-expected.cc\n│       ├── iterator-loops-negative-original.cc\n│       └── iterator-loops-negative-expected.cc\n├── scripts/\n│   ├── apply_edits.py            # Applies edits (no git dependency)\n│   ├── build_gen_targets.sh      # Build CEF-related gen targets only\n│   ├── build_clang_rewriter.sh   # Bootstrap clang with the tool\n│   ├── package_standalone.sh     # Package for standalone use\n│   ├── process_edits.py          # Adds markers, deduplicates edits\n│   ├── run_tool.py               # Run tool on CEF files\n│   └── test_tool.py              # CEF-specific test harness\n├── standalone/\n│   ├── README.md                 # Standalone usage documentation\n│   └── run_rewriter.py           # Standalone wrapper script\n├── CLAUDE.md\n├── README.md\n└── TRANSFORMS.md                 # Transformation documentation\n```\n\n## Maintenance\n\nThis tool is not regularly tested. It may need updates when:\n\n| Trigger | Likely Fix |\n|---------|------------|\n| Chromium updates `tools/clang/` infrastructure | Update `CMakeLists.txt`, check `build.py` flags |\n| LLVM/Clang API changes | Update AST matcher syntax, check deprecations in Clang doxygen |\n| CEF adopts C++23 | Add `flat_map`/`flat_set` container types to matcher |\n| Build fails after Chromium update | Compare with current `tools/clang/ast_rewriter/` example |\n\n### Diagnosing Build Failures\n\nIf the tool fails to build after a Chromium update:\n\n1. Check if `ast_rewriter` still exists and builds:\n    ```bash\n    python3 tools/clang/scripts/build.py --bootstrap --extra-tools ast_rewriter\n    ```\n\n2. Compare CMakeLists.txt with the current ast_rewriter version:\n    ```bash\n    diff cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt tools/clang/ast_rewriter/CMakeLists.txt\n    ```\n\n3. Check for API changes in Clang's AST matchers (review Clang release notes)\n\n### Cleanup\n\nAfter running the tool, you may want to remove the symlink:\n\n```bash\nrm tools/clang/cef_cpp_rewriter  # Removes symlink only, not CEF source\n```\n\n## Resources\n\n- Chromium clang tool documentation: `docs/clang_tool_refactoring.md`\n- Chromium example: `tools/clang/ast_rewriter/`\n- [AST Matcher Reference](https://clang.llvm.org/docs/LibASTMatchersReference.html)\n- [LibTooling Tutorial](https://clang.llvm.org/docs/LibASTMatchersTutorial.html)\n","tools/clang/standalone/README.md":"# C++ Rewriter Tool\n\nA clang-based AST rewriter for C++20 modernization. This tool performs\ntype-aware code transformations that cannot be done with simple regex,\nsuch as replacing `map.find(x) != map.end()` with `map.contains(x)`.\n\n## Distribution Contents\n\nThis is a self-contained distribution that includes everything needed to run:\n\n```\ncpp_rewriter/\n├── bin/\n│   └── cpp_rewriter           # The clang-based rewriter tool\n├── lib/\n│   └── clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n│       └── include/\n├── scripts/\n│   ├── run_rewriter.py        # Main wrapper script\n│   ├── apply_edits.py         # Applies generated edits to files\n│   └── process_edits.py       # Deduplicates and formats edits\n└── README.md\n```\n\nThe bundled `lib/clang/` headers are automatically detected and used by the\nwrapper script, so the tool works without requiring a matching system clang.\n\n## Prerequisites\n\n- A C++ project with a `compile_commands.json` file\n- Python 3.6+\n\n## Generating compile_commands.json\n\nThe tool requires a compilation database to understand your project's\nbuild configuration. Here's how to generate one for common build systems:\n\n### CMake\n\n**Important:** `CMAKE_EXPORT_COMPILE_COMMANDS` only works with **Makefile**\nand **Ninja** generators. It does NOT work with Xcode or Visual Studio generators.\n\n```bash\n# Using Ninja (recommended)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Using Unix Makefiles\ncmake -G \"Unix Makefiles\" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# compile_commands.json is now in build/\n```\n\nIf you normally use Xcode/Visual Studio, create a separate build directory\njust for tooling:\n\n```bash\n# Keep your Xcode build, add a parallel Ninja build for tools\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build-tools\n# Use build-tools/compile_commands.json with the rewriter\n```\n\n### Meson\n\n```bash\nmeson setup build\n# compile_commands.json is automatically generated in build/\n```\n\n### Bear (for Make-based projects)\n\n```bash\n# Install Bear: https://github.com/rizsotto/Bear\nbear -- make\n# compile_commands.json is generated in current directory\n```\n\n### Ninja\n\n```bash\nninja -C build -t compdb > build/compile_commands.json\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Run on all files in compile_commands.json\n./scripts/run_rewriter.py -p /path/to/build | ./scripts/apply_edits.py --base-dir /path/to/build\n\n# Run on specific source directories only\n./scripts/run_rewriter.py -p build src/ include/ | ./scripts/apply_edits.py --base-dir build\n```\n\n### Filter by Path Pattern\n\nUse `--path-filter` with a substring to process only matching files:\n\n```bash\n# Only process files containing \"src/core/\" in their path\n./scripts/run_rewriter.py -p build --path-filter \"src/core/\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Disable Specific Transformations\n\n```bash\n# Disable structured bindings transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--structured-bindings=false\" | ./scripts/apply_edits.py --base-dir build\n\n# Run only the .contains() transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--only=contains\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Verbose Output\n\n```bash\n# Show progress\n./scripts/run_rewriter.py -p build -v src/ 2>&1 | tee /tmp/edits.txt\n./scripts/apply_edits.py --base-dir build < /tmp/edits.txt\n```\n\n## Available Transformations\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nAll transformations are enabled by default. Use `--flag=false` to disable specific ones,\nor `--only=<list>` to run only specific transformations.\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags,\nbefore/after examples, supported containers, and edge cases.\n\n## Troubleshooting\n\n### \"compile_commands.json not found\"\n\nMake sure you've generated the compilation database. See the\n\"Generating compile_commands.json\" section above.\n\n### \"No files found matching...\"\n\n- Check that the path filter matches your file paths\n- Use `-v` for verbose output to see which files are being processed\n- Try running without a path filter first\n\n### Transformations not applying\n\n- The tool only transforms code, not macro expansions\n- Some patterns may not match due to unusual formatting\n- Use `-v` to see error messages from the tool\n\n## Compatibility\n\nThe transformed code uses C++20 features. See [TRANSFORMS.md](TRANSFORMS.md) for\nminimum compiler requirements.\n\n## Building from Source\n\nThis tool is built as part of the CEF (Chromium Embedded Framework) project.\nSee the CEF repository for build instructions.\n","tools/claude/README.md":"# Tools and Detailed Instructions for CEF Development\n\nThis directory contains tools and detailed instructions for using coding\nagents to assist with CEF (Chromium Embedded Framework) development. Use these\nguides with models that benefit from explicit workflows, examples, and\nverification steps, including Claude Opus 4.x and GPT Terra.\n\nThe guides were originally written for Claude Code and retain their `CLAUDE_*`\nfilenames. Other coding agents can use them directly; adapt any Claude-specific\nsetup or file attachment syntax to your agent. For GPT Sol or other frontier\nmodels that work well with concise instructions, see the\n[GPT guides](../gpt/README.md) for concise patch and build instructions and\nexample prompts. For other tasks, newer frontier models can often discover the\nrelevant details themselves, using the detailed instruction files here as\nreference material when needed.\n\n***\n[TOC]\n***\n\n## Quick Navigation\n\n**Are you updating CEF to a new Chromium version?**\n\n→ See [CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md) for the complete workflow:\n\n- Fixing patches that fail to apply\n- Fixing build errors from API changes\n- Using analyzer scripts and verification tools\n\n**Are you developing a CEF application using a binary distribution?**\n\n→ See [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md) for implementing features:\n\n- Adding custom URL schemes\n- JavaScript-to-C++ communication\n- Network request interception\n- Popup window customization\n\n**Are you writing or debugging CEF unit tests?**\n\n→ See [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md) for working with ceftests:\n\n- Running existing unit tests\n- Creating new tests for CEF features\n- Debugging test failures and flakiness\n- Using TestHandler, RoutingTestHandler, and TestServer\n\n**Are you developing libcef internals (CEF implementation code)?**\n\n→ See [CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md) for libcef development patterns:\n\n- Adding new CEF APIs with proper versioning\n- Implementing WebContentsDelegate callbacks\n- Working with Chrome and Alloy browser styles\n- Finding and fixing NOTIMPLEMENTED() stubs\n\n**Are you syncing CEF base headers with Chromium?**\n\n→ See [CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md) for synchronizing `cef/include/base/` headers:\n\n- CEF-specific modifications (namespaces, includes, platform macros)\n- Files to sync vs files to preserve\n- Handling C++23 reverts\n- Step-by-step sync process\n\n**Are you cherry-picking commits from upstream CEF?**\n\n→ See [CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md) for cherry-picking commits that include patch files:\n\n- Extracting and applying source file changes from patches\n- Resaving patches with correct index hashes\n- Handling multiple patch files per commit\n- Recovery when things go wrong\n\n**Are you applying a Chromium commit to CEF as a patch?**\n\n→ See [CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md) for creating or updating CEF patches from Chromium commits:\n\n- Creating new patch files and adding to patch.cfg\n- Adding changes to existing patch files\n- Handling version differences between Chromium versions\n- Verifying patches can be reverted and reapplied\n\n**Are you improving unit test coverage?**\n\n→ See [CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md) for running and analyzing code coverage:\n\n- Human prerequisites for setting up coverage builds\n- Building and running tests with coverage instrumentation\n- Analyzing coverage reports to identify gaps\n- Workflow for improving function and line coverage\n\n## Files in This Directory\n\n### Documentation\n\n- **[CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md)** - Complete guide for updating CEF to new Chromium versions\n- **[CLAUDE.md.in](CLAUDE.md.in)** - Template for root CLAUDE.md (copied by setup_claude.py)\n- **[CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md)** - Instructions for syncing CEF base headers with Chromium\n- **[CLAUDE_BUILD_INSTRUCTIONS.md](CLAUDE_BUILD_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing build errors\n- **[CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md)** - Instructions for cherry-picking commits from upstream CEF that include patch files\n- **[CLAUDE_CLIENT_INSTRUCTIONS.md](CLAUDE_CLIENT_INSTRUCTIONS.md)** - Detailed instructions for Claude agents implementing features in CEF applications\n- **[CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md)** - Instructions for running and analyzing code coverage\n- **[CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md)** - Detailed instructions for Claude agents developing libcef internals (API versioning, WebContentsDelegate)\n- **[CLAUDE_PATCH_INSTRUCTIONS.md](CLAUDE_PATCH_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing patch failures\n- **[CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md)** - Instructions for applying Chromium commits to CEF as new or existing patches\n- **[CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md)** - Detailed instructions for Claude agents creating and running CEF unit tests\n- **[CLAUDE_WIKI_INSTRUCTIONS.md](CLAUDE_WIKI_INSTRUCTIONS.md)** - Bitbucket wiki formatting guidelines for Claude agents\n- **[CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md)** - Complete guide for CEF client application development\n- **[README.md](README.md)** - This file\n\n### Python Tools\n\n- **[analyze_build_output.py](analyze_build_output.py)** - Analyze and format ninja build output with error index\n- **[analyze_coverage_output.py](analyze_coverage_output.py)** - Analyze LLVM coverage reports and identify coverage gaps\n- **[analyze_patch_output.py](analyze_patch_output.py)** - Analyze and format `patch_updater.py` output with file movement detection\n- **[patch_utils.py](patch_utils.py)** - Shared utilities for patch analysis tools (file movement detection)\n- **[verify_patch.py](verify_patch.py)** - Verify that regenerated patches include all changes from reject files\n- **[format_wiki.py](format_wiki.py)** - Apply Bitbucket wiki formatting guidelines to markdown files (supports wildcards; also integrated into `../fix_style.py`)\n\n### Test Files\n\n- **[analyze_build_output_test.py](analyze_build_output_test.py)** - Unit tests for analyze_build_output.py\n- **[analyze_coverage_output_test.py](analyze_coverage_output_test.py)** - Unit tests for analyze_coverage_output.py\n- **[analyze_patch_output_test.py](analyze_patch_output_test.py)** - Unit tests for analyze_patch_output.py\n- **[patch_utils_test.py](patch_utils_test.py)** - Unit tests for patch_utils.py\n- **[verify_patch_test.py](verify_patch_test.py)** - Unit tests for verify_patch.py\n- **[format_wiki_test.py](format_wiki_test.py)** - Unit tests for format_wiki.py\n\n## Common Setup\n\nFor Chromium update workflows, run the setup script:\n\n```bash\ncd chromium/src/cef/tools\npython3 setup_claude.py\n```\n\nThis copies `CLAUDE.md.in` to the project root as `chromium/src/CLAUDE.md`, enabling Claude Code to understand the Chromium/CEF codebase structure.\n\n## Formatting Files\n\nThe `fix_style.py` tool in `//cef/tools/` formats C/C++, Python, and Markdown files:\n\n```bash\n# From chromium/src/cef/tools directory:\n\n# Format single markdown file\npython3 fix_style.py claude/CLAUDE_TEST_INSTRUCTIONS.md\n\n# Format all CLAUDE instruction files\npython3 fix_style.py claude/CLAUDE_*.md\n\n# Format all markdown files in claude directory\npython3 fix_style.py claude/*.md\n\n# Format all staged files (including markdown)\npython3 fix_style.py staged\n```\n\nThe markdown formatter applies [Bitbucket wiki formatting guidelines](CLAUDE_WIKI_INSTRUCTIONS.md) (blank lines before lists, 4-space indentation, etc.).\n\n## Tips for Working with Claude Code\n\nThese tips apply to both Chromium updates and client development:\n\n### 1. Provide Context\n\nAlways include relevant version numbers or distribution details:\n\n**For Chromium updates:**\n```\nOld version: 139.0.7258.0\nNew version: 140.0.7339.0\n```\n\n**For client development:**\n```\nCEF binary distribution: cef_binary_142.0.10+g29548e2+chromium-142.0.7444.135_macosarm64\n```\n\n### 2. Attach Relevant Files\n\nUse `@filename` to attach files Claude should read:\n\n- `@cef/tools/claude/patch_analysis.txt` - Analyzed patch output\n- `@cef/tools/claude/build_analysis.txt` - Analyzed build output\n- `@cef/tools/claude/CLAUDE_CHERRY_PICK_INSTRUCTIONS.md` - Cherry-picking upstream commits\n- `@cef/tools/claude/CLAUDE_CLIENT_INSTRUCTIONS.md` - Client development guide\n- `@cef/tools/claude/CLAUDE_SRC_PATCH_INSTRUCTIONS.md` - Applying Chromium commits as patches\n- `@cef/tools/claude/CLAUDE_TEST_INSTRUCTIONS.md` - CEF unit testing guide\n\n**Tip:** In large directory structures like `chromium/src`, the `@` syntax can be slow. Use `//` syntax for workspace-relative paths instead (e.g., `//cef/tools/claude/patch_analysis.txt`).\n\n### 3. Let Claude Work Systematically\n\nDon't interrupt mid-stream unless necessary. Claude will:\n\n- Create TODO lists\n- Work through items one by one\n- Report progress regularly\n- Ask for help when stuck\n\n### 4. Use Incremental Prompts\n\nFor large tasks, you can guide Claude incrementally:\n\n**For Chromium updates:**\n```\n1. \"Start fixing patches using @CLAUDE_PATCH_INSTRUCTIONS.md\"\n2. [Claude works for a while]\n3. \"Good progress. Continue with the remaining patches.\"\n4. [Claude finishes]\n5. \"Now let's fix build errors using @CLAUDE_BUILD_INSTRUCTIONS.md\"\n```\n\n**For unit testing:**\n```\n1. \"Create tests for the new feature using @CLAUDE_TEST_INSTRUCTIONS.md\"\n2. [Claude creates tests]\n3. \"Run the tests and fix any failures\"\n4. [Claude debugs and fixes]\n5. \"Good, now verify they work in both Chrome and Alloy styles\"\n```\n\n### 5. Ask for Summaries\n\nAfter a session:\n```\nPlease summarize all the changes you made, organized by category.\n```\n\nClaude can provide a detailed summary for documentation or commit messages.\n\n### 6. Use the Analyzers Proactively\n\nFor Chromium updates, run the analyzers yourself first to understand the scope:\n\n**For patches:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_patch_output.py patch_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > patch_analysis.txt\n```\n\n**For build errors:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_build_output.py build_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > build_analysis.txt\n```\n\nThen share the analysis files with Claude.\n\n## Getting Help\n\n### For Issues with Tools\n\n- Check the guide files and instruction files listed above for usage examples\n- Check analyzer script help: `python3 analyze_patch_output.py --help`\n\n### For Issues with CEF\n\n- CEF wiki: https://github.com/chromiumembedded/cef/blob/master/docs/README.md\n- CEF forums: https://magpcss.org/ceforum/\n- CEF issue tracker: https://github.com/chromiumembedded/cef/issues\n\n### For Issues with Claude Code\n\n- Claude Code documentation: https://docs.claude.com/claude-code\n- Improve prompts with more context and specific examples\n- Break large tasks into smaller, more manageable pieces\n\n## Contributing\n\nIf you improve these tools or instructions:\n\n1. Test with a real Chromium update, client development task, or unit testing workflow\n2. Document what you changed and why\n3. Update the appropriate guide ([CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md), [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md), or [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md))\n4. Share improvements with the CEF community\n\n## License\n\nThese tools are part of the CEF project and follow the same license as CEF (BSD license).\n","tools/debug/ax_viewport_collapse/README.md":"# ax_viewport_collapse Debug Tools\n\nManual verification tools for the `ax_viewport_collapse` CefBrowserSettings feature.\nThese connect to a running cefclient via CDP to inspect the accessibility tree.\n\n## Prerequisites\n\n```\npython3 -m pip install websocket-client\n```\n\n## Usage\n\n### 1. Launch cefclient with remote debugging\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\n```\n\nThe `--ax-viewport-collapse` flag maps to `CefBrowserSettings.ax_viewport_collapse = STATE_ENABLED` in cefclient.\n\nTo load the test page directly:\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse --url=file:///<path>/test_viewport_collapse.html\n```\n\n### 2. Run the verification script\n\n```\npython3 verify_viewport_collapse.py\n```\n\nOr navigate to a URL first:\n\n```\npython3 verify_viewport_collapse.py --url https://example.com\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `--host` | CDP host (default: `127.0.0.1`) |\n| `--port` | CDP port (default: `9222`) |\n| `--url` | Navigate to URL before fetching tree |\n| `--raw` | Print full JSON response instead of summary |\n\n### Comparing with/without collapse\n\nRun two cefclient instances on different ports:\n\n```\ncefclient.exe --cache-path=<path1> --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\ncefclient.exe --cache-path=<path2> --remote-debugging-port=9223 --remote-allow-origins=*\n```\n\n```\npython3 verify_viewport_collapse.py --port 9222 --raw > with.json\npython3 verify_viewport_collapse.py --port 9223 --raw > without.json\ndiff with.json without.json\n```\n\n### Expected output (with collapse enabled)\n\n```\nAX Tree Summary\n============================================================\nTotal nodes returned:  77\n  Ignored:             3\n  Full (with children):70\n  Summary (collapsed): 4\n\nCollapsed summary nodes (off-screen landmarks/headings):\n------------------------------------------------------------\n  region: \"Content preferences\"\n  region: \"Audio quality\"\n  region: \"Display\"\n  region: \"Storage\"\n```\n\nOff-screen landmark sections appear as leaf nodes with role + name only. In-viewport nodes are fully serialized with children.\n\n## Files\n\n- `verify_viewport_collapse.py` — CDP script that calls `Accessibility.getFullAXTree()` and prints a summary or raw JSON\n- `test_viewport_collapse.html` — Test page with 6 landmark sections, 2 in viewport and 4 pushed off-screen by a spacer\n","tools/gpt/README.md":"# GPT Instructions for CEF Updates\n\nUse these guides when asking a coding agent to update CEF patches or fix build\nerrors during a Chromium update. The GPT guides give Sol a short overview of\nwhat to do and how to verify the result. They link to the existing Claude\nguides for detailed commands, examples, and troubleshooting.\n\n## Choosing a model\n\n| Model | Starting effort | Guides to use |\n| --- | --- | --- |\n| GPT-6.1 Sol | Low | The GPT guides in this directory |\n| GPT-5.6 Terra | Choose for your task | The Claude guides in `cef/tools/claude/` |\n\nFor Sol, start with low effort and use the Sol examples below. The agent can\nconsult the linked Claude guides as it works. For Terra, use the Terra examples,\nwhich point directly to the detailed Claude guides. Those guides work with\nother models despite their filenames.\n\nSelect the model and effort in your coding agent before sending the prompt.\nThe instruction files describe the work; model selection is a separate setting.\n\nThese recommendations are a starting point for trying the workflows on real\nupdates. Adjust the GPT model and reasoning effort to balance speed and cost\nwhile meeting the same completion checks. Check whether the agent covers every\nfailed file, preserves CEF behavior, and saves source fixes into the patches.\nIf Sol gets stuck on a particular issue or cannot explain why a behavioral\nchange is correct, try that issue again at medium effort. When comparing speed\nand cost, include any follow-up work needed to correct the result.\n\n## Getting started\n\nBefore launching the agent, use the existing Chromium update guide to prepare\nyour checkout and the analysis for the phase you're working on:\n\n1. Review the [complete update workflow](../claude/CHROMIUM_UPDATE.md#complete-update-workflow)\n   for the order of checkout updates, patch repairs, builds, and testing.\n2. Check the [prerequisites](../claude/CHROMIUM_UPDATE.md#prerequisites) and\n   [setup](../claude/CHROMIUM_UPDATE.md#setup): you'll need a Chromium checkout\n   with CEF integration, Python 3, and the appropriate build configuration.\n   The `setup_claude.py` step installs context for Claude Code; it is not a\n   prerequisite for using the GPT prompts.\n3. For patch repairs, follow [Phase 1: Fixing Patches](../claude/CHROMIUM_UPDATE.md#phase-1-fixing-patches)\n   to capture `patch_updater.py` output and generate `patch_analysis.txt` with\n   your old and new Chromium versions. Then use the patch prompt below.\n4. Once the patches apply cleanly, follow [Phase 2: Fixing Build Errors](../claude/CHROMIUM_UPDATE.md#phase-2-fixing-build-errors)\n   to capture a build of your chosen target and generate `build_analysis.txt`.\n   Then use the build prompt below.\n\nStart your coding agent from the `chromium/src` checkout root. Copy one of the\ncomplete prompts below, then replace the Chromium versions and analysis path\nwith yours. For a build task, also set your output directory and build target.\nAll paths in the prompts are relative to `chromium/src`.\n\nUse the analysis files produced by the existing tools in `cef/tools/claude/`:\n\n- `patch_analysis.txt` lists failed patches and files.\n- `build_analysis.txt` lists build errors and points to the relevant sections\n  of `build_output.txt`.\n\nThe build examples include permission to fix Chromium files outside `cef/`\nwhen custom CEF patches cause their build failures. Keep that instruction if\nit applies to your update: it tells the agent to save those fixes into the\nassociated CEF patches and overrides the detailed build guide's usual scope.\n\n## Example prompts for Sol at low effort\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/gpt/GPT_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. Fix those build\nerrors and re-save the associated CEF patch files using\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n\n## Example prompts for Terra\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. You should also\nfix those build errors and re-save the associated CEF patch files using\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md. This extends the build\nguide's default restriction to files under cef.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n"},"items":[{"name":"AGENTS.md","path":"tools/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/AGENTS.md","title":"tools - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# CEF Tools Contributor and Agent Guidelines\n\nThis file applies to `//cef/tools` and its descendants.\n\n## Generator inventory and coverage\n\n- Every direct-child, non-test `make_*.py` generator must have a matching\n  `make_*_test.py` module.\n- `make_generator_inventory_test.py` enforces the direct-child inventory. When\n  adding or removing a generator, update its expected count intentionally and\n  keep nested generators, helpers, and existing tests out of the inventory.\n- Exercise every top-level generator function through at least one successful\n  test. Cover meaningful explicit error branches, writer behavior, and the\n  generator's CLI style; do not treat filename coverage as function coverage.\n- Use standard-library `unittest`, `tempfile`, and `unittest.mock`. Run from the\n  CEF root:\n\n  ```sh\n  python3 -m unittest discover -s tools -p '*_test.py'\n  python3 -m unittest discover -s tools -p 'make_example_test.py' -v\n  ```\n\n- Run the complete suite twice for generator-wide work. These modules share\n  parser state, so the second run detects ordering and cleanup leaks.\n\n## Hermetic fixtures and goldens\n\n- Put deterministic inputs and reviewed goldens under\n  `tools/testdata/make_generators/`; use `generator_test_util.py` for shared\n  fixture, manifest, archive, and CLI helpers.\n- Mock or fix time, year, Git metadata, versions, platforms, environment\n  variables, external commands, and formatter results when they affect output.\n- Goldens must originate from a reviewed baseline, never from ignored\n  working-tree output, and tests must not contain an auto-update path.\n- Use inline expectations for small output and reviewed full-file goldens for\n  larger generated C/C++ content. Add targeted assertions that explain the\n  behavior protected by a golden.\n- Prove that customized CppToC/CToCpp bodies survive regeneration, source\n  fixtures are not modified, and relevant paths work when they contain spaces.\n\n## Writer contracts\n\n- Test every writer on its first generation and an identical second\n  generation.\n- For `write_file_if_changed`, assert changed/unchanged returns and preserved\n  mtime. For unconditional writers, assert stable bytes across rewrites.\n- Multi-output writers must report a change when any output changes. Test\n  repairs where only one output was corrupted.\n- Pre-publication failures must leave outputs missing or unchanged. Characterize\n  partial I/O-failure output before changing it; atomic publication is a\n  separate behavior change.\n\n## CLI contracts\n\n- Cover invalid status, stdout, stderr, and partial artifacts, plus successful\n  stdout, single-file, multi-output, argparse, and distribution CLI styles.\n- If a generator function returns metadata with its content, such as\n  `(content, customized)`, unpack the result at the CLI boundary and write only\n  the string content. Do not change the underlying generator return contract\n  merely to fix a CLI.\n- Assert progress messages exactly when callers may depend on them, and return\n  explicit nonzero statuses for rejected invocations.\n\n## Parser and module state\n\n- Restore parser notification context and other module globals with\n  `try/finally`; add test cleanup so failing regressions cannot leak state.\n- Generator modules intended for reuse must be importable without parsing\n  arguments, exiting, mutating files, calling Git, or launching subprocesses.\n  Put orchestration in `main(argv=None)` and use a conventional guarded entry\n  point when refactoring for importability.\n\n## Output equivalence\n\n- Establish an exact pre-refactor baseline and keep testability refactors\n  separate from behavior fixes.\n- Testability refactors must preserve generated bytes, paths, ordering,\n  comments, whitespace, guards, encoding, newlines, modes, and symlink targets.\n- Compare fixes to the latest approved baseline while retaining the original\n  refactor baseline as an immutable reference.\n- Return-value, status, diagnostic, and CLI changes must not alter generated\n  files unless that is their documented purpose.\n- For translator changes, run a repository-scale comparison covering C API,\n  CppToC, CToCpp, wrapper, dylib, and GYPI outputs.\n- For distribution changes, compare the complete normalized tree. Compare\n  archive member paths, types, uncompressed bytes, and modes; normalize archive\n  timestamps only. Do not use raw archive-container hashes as equivalence.\n- Use the same Python interpreter as the recorded baseline. Python-version\n  differences can change comment wrapping and produce misleading byte deltas.\n\n## Bug-fix workflow\n\n- Reproduce a bug with a focused regression before changing production code.\n- Keep coverage/refactor checkpoints separate from behavior fixes so output\n  differences cannot be attributed to the wrong change.\n- Keep unrelated bugs independently reviewable. Closely related instances of\n  the same root cause may be grouped when explicitly requested.\n\n## Formatting and validation\n\n- From the CEF root, format only explicit changed Python paths:\n\n  ```sh\n  python3 tools/fix_style.py tools/make_example.py tools/make_example_test.py\n  ```\n\n- Inspect formatter output immediately. The formatter may rewrap unrelated\n  legacy code; revert that churn with targeted patches.\n- Compile every changed generator, helper, and test.\n- Run `git diff --check` and scan untracked files for trailing whitespace.\n- Re-run focused tests after formatting, then run the complete suite twice.\n","isInternal":false,"tokens":1130,"sizeBytes":5429},{"name":"CLAUDE.md","path":"tools/CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/CLAUDE.md","title":"tools - Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"@AGENTS.md\n","isInternal":false,"tokens":5,"sizeBytes":11},{"name":"CLAUDE.md","path":"tools/clang/CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/clang/CLAUDE.md","title":"Clang Skill","category":"anthropic-skill","format":"markdown","content":"# CEF Clang Tools - Claude Code Instructions\n\nThis file provides guidance to Claude Code when working with CEF clang tools.\n\n## Overview\n\nThe `cef_cpp_rewriter` tool is a clang AST-based rewriter for C++20 modernization.\nIt uses Clang's LibTooling and AST matchers to perform type-aware transformations\nthat cannot be done with simple regex.\n\n**Supported transformations:** `.contains()`, structured bindings, iterator loops,\nDISALLOW_COPY_AND_ASSIGN. See [TRANSFORMS.md](TRANSFORMS.md) for complete documentation.\n\n**Important:** CEF is a separate git repository within chromium/src. Chromium's\nclang tool scripts use git commands that don't work across repository boundaries.\nUse the CEF-specific scripts in `cef/tools/clang/scripts/` instead.\n\n## Key Files\n\n- `cef/tools/clang/cef_cpp_rewriter/CefCppRewriter.cpp` - Main tool implementation\n- `cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt` - Build configuration\n- `cef/tools/clang/scripts/build_clang_rewriter.sh` - Bootstrap script\n- `cef/tools/clang/scripts/package_standalone.sh` - Package for standalone use\n- `cef/tools/clang/standalone/` - Standalone distribution files\n- `cef/tools/clang/cef_cpp_rewriter/tests/` - Test cases\n\n## Prerequisites\n\n**Python 3.10+ required.** Chromium's build scripts use type union syntax that requires Python 3.10+. On macOS:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\n```\n\n## Development Workflow\n\n### Building the Tool\n\nAfter modifying `CefCppRewriter.cpp`:\n\n```bash\n# Fast incremental rebuild (~seconds)\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Never re-run `build_clang_rewriter.sh`** unless the build directory was deleted.\nIt rebuilds clang from scratch (~30 minutes).\n\n### Testing Matchers with clang-query\n\n```bash\nexport PATH=$PATH:third_party/llvm-build/Release+Asserts/bin\nclang-query /tmp/test.cc --\n```\n\n### Generating compile_commands.json for Manual Testing\n\nThe `test_tool.py` script generates this automatically, but for manual testing:\n\n```bash\n# macOS (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -isysroot $(xcrun --show-sdk-path) -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Linux (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Run the tool (--disable-path-filter needed for test files)\nthird_party/llvm-build/Release+Asserts/bin/cef_cpp_rewriter \\\n  --disable-path-filter -p $TEST_DIR $TEST_DIR/contains-original.cc\n```\n\n### Running Tests\n\n```bash\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n### Debugging\n\n1. Add `dumpColor()` calls in `run()` to visualize matched AST nodes\n2. Return 1 from `main()` to see tool output (run_tool.py hides output on success)\n3. Dump AST: `clang++ -Xclang -ast-dump -std=c++20 file.cc`\n\n## Important Constraints\n\n1. **Symlink required**: The tool must be symlinked to `tools/clang/cef_cpp_rewriter`\n2. **Do not transform std::string**: Only associative containers have C++20 `.contains()`\n3. **Same container check**: Verify `find()` and `end()` are called on the same object\n4. **Skip macros**: Don't transform code inside macro expansions\n5. **CEF paths only**: Only transform files containing `/cef/` in their path\n\n## Compatibility Requirements\n\nCEF targets C++20. All transformations must work with these minimum toolchain versions:\n\n- GCC 10 (CEF minimum)\n- macOS 12.0 deployment target\n\nFeatures to AVOID (incompatible):\n\n- `std::string::contains()` - C++23, needs GCC 11+\n- `std::format` - needs GCC 13+ and macOS 13.3+\n- `using enum` - needs GCC 11+\n\n## Adding New Transformations\n\n### Quick Steps\n\n1. Add a command-line flag in `CefCppRewriter.cpp`:\n    ```cpp\n    static llvm::cl::opt<bool> EnableNewFeature(\"new-feature\",\n        llvm::cl::desc(\"Enable new feature transformation\"),\n        llvm::cl::init(true));\n    ```\n\n2. Create a new `MatchCallback` class for the transformation\n\n3. Add matcher to `match_finder` in `main()` guarded by the flag\n\n4. Add test files: `tests/newfeature-original.cc` and `tests/newfeature-expected.cc`\n\n5. Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n   (test_tool.py generates compile_commands.json automatically)\n\n### Full Implementation Checklist Template\n\nUse this checklist when implementing any new transformation:\n\n```markdown\n### Phase N: [Transformation Name]\n**Priority:** Nth | **Complexity:** Low/Medium/High | **Compat:** GCC X+\n\n[Brief description of the transformation]\n\n**Before/After Example:**\n```cpp\n// Before\n[old code pattern]\n\n// After\n[new code pattern]\n```\n\n**Checklist:**\n- [ ] Verify compatibility with GCC 10 and macOS 12.0 deployment target\n- [ ] Add `--flag-name` command-line flag (default: true/false)\n- [ ] Implement `TransformNameRewriter` class with:\n  - [ ] `run()` method that handles matched nodes\n  - [ ] Macro expansion filtering (`isMacroID()`, `isMacroBodyExpansion()`)\n  - [ ] System header filtering (`isInSystemHeader()`)\n  - [ ] Path filtering (skip non-CEF files unless `--disable-path-filter`)\n  - [ ] Deduplication via `processed_locations_` set\n- [ ] Create AST matcher(s) - test with `clang-query` first\n- [ ] Add matcher to `match_finder` in `main()` guarded by flag\n- [ ] Create test files: `transform-name-original.cc`, `transform-name-expected.cc`\n- [ ] Create negative test cases: `transform-name-negative-original.cc` (copy to `-expected.cc`)\n- [ ] Rebuild tool: `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n- [ ] Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n- [ ] Run on CEF code: `python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool --tool-args=\"--flag-name\" cef/libcef cef/libcef_dll cef/tests`\n- [ ] Review diffs and verify correctness\n- [ ] Build CEF to verify no compile errors\n- [ ] Run CEF tests to verify no regressions\n- [ ] Search for skipped instances (macros, edge cases) using grep\n- [ ] Manually transform skipped instances if appropriate\n- [ ] Update TRANSFORMS.md with transformation details\n- [ ] Update CLAUDE.md tool arguments table\n- [ ] Update README.md tool arguments table and transformations list\n```\n\n### Rewriter Class Template\n\n```cpp\nclass NewFeatureRewriter : public MatchFinder::MatchCallback {\n public:\n  explicit NewFeatureRewriter(OutputHelper* output) : output_helper_(*output) {}\n\n  void reset() { processed_locations_.clear(); }\n\n  void run(const MatchFinder::MatchResult& result) override {\n    const auto* matched_node = result.Nodes.getNodeAs<NodeType>(\"bindingName\");\n    if (!matched_node) return;\n\n    const SourceManager& sm = *result.SourceManager;\n    const LangOptions& opts = result.Context->getLangOpts();\n\n    // Skip macros\n    if (matched_node->getBeginLoc().isMacroID() ||\n        sm.isMacroBodyExpansion(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Skip system headers\n    if (sm.isInSystemHeader(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Deduplicate\n    unsigned offset = sm.getFileOffset(matched_node->getBeginLoc());\n    if (processed_locations_.count(offset)) return;\n\n    // Path filter\n    if (!DisablePathFilter) {\n      StringRef filename = sm.getFilename(matched_node->getBeginLoc());\n      if (!filename.contains(\"/cef/\")) return;\n    }\n\n    processed_locations_.insert(offset);\n\n    // Generate replacement\n    std::string replacement = /* ... */;\n    CharSourceRange range = CharSourceRange::getTokenRange(\n        matched_node->getSourceRange());\n    output_helper_.Replace(range, replacement, sm, opts);\n  }\n\n private:\n  OutputHelper& output_helper_;\n  std::set<unsigned> processed_locations_;\n};\n```\n\n### Common Pitfalls\n\n1. **Iterator comparisons use overloaded operators**: Use `cxxOperatorCallExpr(hasOverloadedOperatorName(\"!=\"))` not `binaryOperator`\n2. **Integer literals need implicit cast handling**: Use `ignoringImpCasts(integerLiteral(...))`\n3. **Pointer access needs separate matching**: Include `hasType(pointsTo(...))` in an `anyOf()`\n4. **Token vs char ranges**: `getTokenRange()` includes full last token, `getCharRange()` is exact\n5. **Don't transform std::string methods**: Many string methods have same names but different semantics\n\n## Running the Tool on CEF Code\n\n```bash\n# Create build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool && cp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run all transformations (default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--contains=false --structured-bindings\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\nExample: `--tool-args=\"--only=iterator-loops\"` runs only the iterator-loops transformation.\n\n## Critical Reminders\n\n1. **Symlink required**: `test_tool.py` looks for tools in `tools/clang/`, so the symlink must exist\n2. **Test naming**: Files must be named `*-original.cc` and `*-expected.cc` (not `-test.cc`)\n3. **Do not transform `std::string::find()`**: Only associative containers have C++20 `.contains()`\n4. **Incremental builds**: Use `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n5. **Do not re-run build.py**: It deletes everything and rebuilds from scratch (~30 min)\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory (from chromium/src)\n./cef/tools/clang/scripts/package_standalone.sh /path/to/cpp_rewriter\n\n# This creates a self-contained distribution:\n# /path/to/cpp_rewriter/\n# ├── bin/cpp_rewriter           # The tool binary (renamed from cef_cpp_rewriter)\n# ├── lib/clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper (auto-detects resource dir)\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\n**Key differences from CEF usage:**\n\n- Uses `--path-filter` for substring matching instead of default `/cef/` filter\n- Bundled clang headers allow tool to work without matching system clang\n- No `--generate-compdb` - requires pre-existing `compile_commands.json`\n- `CMAKE_EXPORT_COMPILE_COMMANDS` only works with Ninja/Makefiles generators (not Xcode/VS)\n\nSee `standalone/README.md` for complete standalone usage documentation.\n","isInternal":false,"tokens":3024,"sizeBytes":11909},{"name":"architecture.md","path":"docs/architecture.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/docs/architecture.md","title":"docs - System Architecture & Module Boundaries","category":"project-spec","format":"markdown","content":"This page provides an overview of the CEF architecture.\n\n**Contents**\n\n- [Overview](#overview)\n- [Dependencies](#dependencies)\n- [Versions](#versions)\n- [History](#history)\n- [Modern Architecture](#modern-architecture)\n- [Common API Usage](#common-api-usage)\n- [C Wrapper API](#c-wrapper-api)\n- [CEF1 (Discontinued)](#cef1-discontinued)\n  - [API Usage](#api-usage)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n- [CEF2 (Discontinued)](#cef2-discontinued)\n- [CEF3](#cef3)\n  - [API Usage](#api-usage)\n  - [Process Considerations](#process-considerations)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n    - [Alloy Runtime Classes](#alloy-runtime-classes)\n    - [Chrome Runtime Classes](#chrome-runtime-classes)\n\n---\n\n# Overview\n\nThe Chromium Embedded Framework (CEF) is an open source project founded by Marshall Greenblatt in 2008 to develop a Web browser control based on the [Google Chromium](http://www.chromium.org/Home) project. CEF currently supports a range of programming languages and operating systems and can be easily integrated into both new and existing applications. It was designed from the ground up with both performance and ease of use in mind. The base framework includes C and C++ programming interfaces exposed via native libraries that insulate the host application from Chromium and Blink implementation details. It provides close integration between the browser control and the host application, which can optionally control resource loading, navigation, context menus, printing, JavaScript bindings and more, while taking advantage of the same performance and HTML5 technologies available in the Google Chrome Web browser.\n\nSee the project [README.md](https://github.com/chromiumembedded/cef/blob/master/README.md) for additional introductory material.\n\n# Dependencies\n\nThe CEF project depends on a number of other projects maintained by third parties. The major projects that CEF depends on are:\n\n  * [Chromium](http://www.chromium.org/Home) - Provides general functionality like network stack, threading, message loop, logging and process control needed to create a fully functional Web browser. Implements \"platform\" code that allows Blink to communicate with V8 and Skia. Many Chromium design documents can be found at http://dev.chromium.org/developers.\n  * [Blink](https://www.chromium.org/blink) (formerly WebKit) - The rendering implementation used by Chromium. Provides DOM parsing, layout, event handling, rendering and HTML5 JavaScript APIs. Some HTML5 implementations are split between the Blink and Chromium code bases.\n  * [V8](https://developers.google.com/v8/) - JavaScript engine.\n  * [Skia](https://skia.org/) - 2D graphics library used for rendering non-accelerated content. More information on how Chromium integrates Skia is available [here](http://www.chromium.org/developers/design-documents/graphics-and-skia).\n  * [Angle](https://chromium.googlesource.com/angle/angle/+/master/README.md) - 3D graphics translation layer for Windows that converts GLES calls to DirectX. More information about accelerated compositing is available [here](http://dev.chromium.org/developers/design-documents/gpu-accelerated-compositing-in-chrome).\n\n# Versions\n\nThere have been three versions of CEF to date.\n\n  * CEF1 - Single process implementation using the Chromium WebKit API (now discontinued).\n  * CEF2 - Multi process implementation built on the Chromium browser (now discontinued).\n  * CEF3 - Multi process implementation using either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\").\n\nOnly the CEF3 version is currently developed and supported. See the \"History\" and \"Modern Architecture\" sections below for background and the [Branches And Building](branches_and_building.md) page for current development information.\n\n# History\n\nIn 2008, when the CEF project started, Chromium was a monolithic application built on top of Apple's [WebKit](https://webkit.org/) rendering engine. Google maintained an in-tree variant of WebKit (called the [Chromium WebKit API](https://www.youtube.com/watch?v=JFzC_Gx76E8)) that added additional functionality specific to Chromium. The first version of CEF (called CEF1) was implemented on top of this Chromium WebKit API and used the default single-process application model supported by WebKit1 at that time (for more details on CEF1 architecture see the \"CEF1\" section below).\n\nUse of the Chromium WebKit API came with some known limitations. For example, that API layer did not support the multi-process model that was the basis for most of Google Chrome's [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md). It also lacked many of the UI features that were becoming necessary to support new web platform features (like device selection dialogs, permissions management, etc). We therefore began a new effort, in 2010, to reimplement CEF (called CEF2) on top of the fully-featured but monolithic Chromium browser UI. The lack of internal API boundaries in the Chromium code at that time made it necessary for us to take an \"all or nothing\" approach. If we could create a CEF browser window based on the complete Chrome UI we would effectively gain access to all of Chrome's capabilities \"for free\" (for more details on CEF2 architecture see the \"CEF2\" section below).\n\nGoogle began acknowledging the validity of the embedded use case for Chromium in 2010 and started work on new internal API boundaries to make embedding easier. The [Chromium Content API](http://www.chromium.org/developers/content-module/content-api), which encapsulated the multi-process application model and provided stub implementations for most web platform features, reached a development stage in late 2011 where it was a viable option for Chromium embedders like CEF. It still didn't provide all of the features that we might like, but it was a \"supported\" API layer. We therefore abandoned the CEF2 effort in early 2012 and focused our efforts instead on the Content API as the more viable embedding option. The existing CEF1 API, which was strongly dependent on WebKit1 and the single-process model, could not be directly ported to the Content API. A new CEF API (called CEF3), with substantial breaking API changes and multi-process support, was released in early 2013 (for more details on CEF3 architecture see the \"Modern Architecture\" and \"CEF3\" sections below).\n\nAlso in 2013, Google decided to [fork the WebKit project](https://blog.chromium.org/2013/04/blink-rendering-engine-for-chromium.html). After renaming it to Blink they removed many of the API boundaries that had previously existed between Chromium and WebKit and effectively deleted the Chromium WebKit API. The multi-process architecture, which was optional in WebKit1, was now a requirement with Chromium/Blink. CEF1, which depended on the Chromium WebKit API, no longer had a viable future and CEF3 became the only path forward.\n\nFast forward another 7 years, to 2020, and the Chromium architecture has again changed substantially. A lot of effort has been spent to define clear architectural layers (sometimes called [components](https://www.chromium.org/developers/design-documents/cookbook/)) in the Chromium/Blink source code. New platforms and new embedders have entered the Chromium ecosystem. And yet, many features desired by CEF users remain stubbornly out of reach in the Chrome UI layer. With this new, more modern, version of Chromium, we decided it was time to revisit our goals from CEF2 and create a new CEF version based on the Chrome UI layer (now called the \"Chrome runtime\" in CEF3). Continue to the \"Modern Architecture\" section for details.\n\n# Modern Architecture\n\nThe modern Chromium code base is composed of architectural layers, with the primary application layers being \"content\" (for the [Content API](http://www.chromium.org/developers/content-module/content-api)) and \"chrome\" (for the Chrome UI layer). The \"content\" layer includes [WebContents](https://source.chromium.org/chromium/chromium/src/+/master:content/public/browser/web_contents.h) as the primary browser object and provides implementations for most of the generic web platform and application/process management functionality. The \"chrome\" layer includes [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) as the primary browser object and provides implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc.\n\nFor historical reasons (outlined above), CEF browser windows have been based on the \"content\" layer WebContents object since the introduction of CEF3 in 2013. Adding support for additional \"chrome\" layer features in that architecture was a serious effort because it involved careful understanding and cherry-picking of the related functionality from \"chrome\" code into the CEF code base. Over time we have added dependencies on the \"chrome\" layer targets to support some features in CEF (such and extensions, PDF viewer and print preview) and to avoid code duplication. As a result, CEF3 binaries in modern times already contained most/all of the code that would be required to launch a stand-alone \"chrome\" Browser window, but simply lacked the mechanism to do so.\n\nIn 2020 we launched a [new effort](https://github.com/chromiumembedded/cef/issues/2969) to implement the CEF3 API on top of a fully-featured \"chrome\" Browser window. To be usable in existing CEF3 client applications the \"chrome\" window needed to support a large subset of CEF3's existing callbacks/intercepts (e.g. loading progress, network requests, etc.), and be inserted into the existing [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) structure. At the same time, it was necessary to substantially refactor the internal CEF (libcef) code to extract functionality that was common to both the old WebContents-based approach and the new Browser-based approach. As part of this refactoring we renamed the existing \"content\" layer implementation to the \"Alloy runtime\" (where Alloy = Chrome + other stuff) and named the new \"chrome\" layer implementation as the \"Chrome runtime\". Proceed to the \"CEF3\" section below for additional feature and implementation details.\n\n# Common API Usage\n\nAll versions of CEF expose a simple, easy-to-use API designed to insulate users from the underlying Chromium and Blink code complexity. Common usage is as follows:\n\n1. Initialize CEF by calling CefInitialize().\n\n2. Perform work on the UI message loop by calling CefRunMessageLoop() or CefDoMessageLoopWork().\n\n3. Create a browser window by calling CreateBrowser() or CreateBrowserSync() and passing in a CefClient instance.\n\n4. Shut down CEF by calling CefShutdown() before the application exits.\n\n# C Wrapper API\n\nThe libcef shared library exports a C API that isolates the user from the CEF runtime and code base. The libcef\\_dll\\_wrapper project, which is distributed in source code form as part of the binary release, wraps this exported C API in a C++ API that is then linked into the client application. The code for this C/C++ API translation layer is automatically generated by the [translator](https://github.com/chromiumembedded/cef/blob/master/tools/translator.README.txt) tool. Direct usage of the C API is described on the [Using The CAPI](using_the_capi.md) page.\n\n# CEF1 (Discontinued)\n\nCEF1 was the initial version of CEF first released in 2008. It was discontinued in 2013 when Google forked the WebKit project and subsequently deleted the Chromium WebKit API. See the \"History\" section above for additional details.\n\nThe single process architecture used by CEF1 integrates Chromium and WebKit directly into the client application. Advantages to the single process architecture included reduced memory usage and closer integration with the client application. For example, having the renderer running in the same process allowed JavaScript bindings to synchronously communicate between client code and renderer code. Disadvantages included [reduced performance](https://github.com/chromiumembedded/cef/issues/304) with certain types of accelerated content, [crashes](https://github.com/chromiumembedded/cef/issues/242) due to plugins like Flash running in the same process, and lack of support for application [security and stability features](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md) that required a multi-process architecture.\n\n## API Usage\n\nBelow is an overview of the main CEF1 interfaces and their uses. Since CEF1 is discontinued we no longer provide detailed usage information.\n\n  * [CefApp](http://magpcss.org/ceforum/apidocs/projects/(default)/CefApp.html) - This interface is passed to CefInitialize() and allows the application to customize global functionality like resource loading and proxy handling.\n  * [CefClient](http://magpcss.org/ceforum/apidocs/projects/(default)/CefClient.html) - This interface is passed to CefCreateBrowser() or CefCreateBrowserSync() and acts as the connection between an individual CEF browser instance and the client application. Additional interfaces for request handling, display handling, etc. are exposed via this interface.\n  * [CefBrowser](http://magpcss.org/ceforum/apidocs/projects/(default)/CefBrowser.html) - Exposes capabilities provided by the browser. This includes back/forward navigation, source retrieval, request loading, etc. A single CefBrowser may have one or more child [CefFrame](http://magpcss.org/ceforum/apidocs/projects/(default)/CefFrame.html) objects.\n\n## Threading Considerations\n\nCEF1 includes UI, IO and FILE threads. The UI thread creates browser windows and is used for all interaction with WebKit and V8. The IO thread is used for handling schema and network requests. The FILE thread is used for the application cache and other miscellaneous activities.\n\nWhen using CEF1 you should keep the following threading considerations in mind:\n\n  * Do not perform blocking operations on the UI thread. This can lead to serious performance issues.\n  * The UI thread will be the same as the main application thread if CefInitialize() is called with a CefSettings.multi\\_threaded\\_message\\_loop value of false.\n  * All WebKit and V8 interation must take place on the UI thread. Consequently, some CEF API functions can only be called on the UI thread. Functions that have this limitation will be documented accordingly in the associated CEF header file.\n  * The [CefPostTask](http://magpcss.org/ceforum/apidocs/projects/(default)/(_globals).html#CefPostTask(CefThreadId,CefRefPtr<CefTask>)) method can be used to post tasks asnychronously between the various threads.\n\n## Implementation Details\n\nCEF1 has the following major implementation classes:\n\n  * CefContext - Represents the global CEF context. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * CefProcess - Used by CefContext to create and manage the CEF threads.\n  * BrowserWebKitInit - Manages the global WebKit environment as exposed by the Chromium WebKit API.\n  * WebViewHost - Provides the native window \"wrapper\" implementation for a WebView. This class extends WebWidgetHost which provides functionality shared in common with popup widgets (like select menus) on some platforms.\n  * CefBrowserImpl - Implements the CefBrowser interface, creates the WebViewHost and provides the glue code for a single browser instance.\n  * BrowserWebViewDelegate - Implements the WebKit interfaces that provide communication between CefBrowserImpl and the underlying WebView.\n\n# CEF2 (Discontinued)\n\nCEF2 was an effort to reimplement the CEF1 API on top of the Chrome browser UI as it existed in 2010. CEF2 was discontinued when Chromium announced support for the Content API. Information about CEF2 can be found in the \"History\" section above and [here](http://magpcss.org/ceforum/viewtopic.php?f=10&t=122) on the CEF Forum.\n\n# CEF3\n\nCEF3 has been the recommended and supported version of CEF since January 2013. It uses the same multi process architecture as the Chromium Web browser via either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\"). This architecture provides a number of advantages over the single process architecture used by CEF1:\n\n  * Support for multi-process run mode (with related [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md)).\n  * More code sharing with the Chromium browser.\n  * Improved performance and less breakage due to use of the \"supported\" code path.\n  * Faster access to new features.\n\nIn most cases CEF3 will have the same performance and stability characteristics as the Chromium Web browser. Both the Alloy runtime and the Chrome runtime support modern web platform features and provide the safety/security expected from an up-to-date Chromium-based browser. The Chrome runtime, which was introduced in 2020, adds implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc. At the time of writing, the Chrome runtime requires use of the [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) in CEF client applications and does not support off-screen rendering. A current list of open issues specific to the Chrome runtime can be found [here](https://github.com/chromiumembedded/cef/issues?q=is%3Aissue+is%3Aopen+label%3Achrome).\n\nStarting with the M125 release (mid-2024) the Alloy runtime has been [split](https://github.com/chromiumembedded/cef/issues/3681) into separate style and bootstrap components. Both Chrome style and Alloy style browsers/windows can now be created while using the Chrome bootstrap. The Alloy bootstrap has been [removed](https://github.com/chromiumembedded/cef/issues/3685) starting with the M128 release.\n\n## API Usage\n\nSee the [General Usage](general_usage.md) page for detailed API usage instructions.\n\n## Process Considerations\n\nSee the [Processes](general_usage.md#processes) section of the [General Usage](general_usage.md) page for details.\n\n## Threading Considerations\n\nSee the [Threads](general_usage.md#threads) section of the [General Usage](general_usage.md) page for details.\n\n## Implementation Details\n\nFor an implementation overview see the \"Modern Architecture\" section above. \n\nShared CEF library/runtime classes use the Cef prefix. Classes that implement the Alloy or Chrome runtime use the Alloy or Chrome prefixes respectively. Classes that extend an existing Chrome-prefixed class add the Cef or Alloy suffix, thereby following the existing naming pattern of Chrome-derived classes.\n\n### Alloy Runtime Classes\n\nAlloy runtime bootstrap was [removed](https://github.com/chromiumembedded/cef/issues/3685) in M128 (mid-2024) and Alloy runtime style is now supported using the Chrome runtime bootstrap. Alloy runtime style is based on the \"content\" layer and has the following major implementation classes:\n\n  * [AlloyBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/alloy/alloy_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n\n### Chrome Runtime Classes\n\nChrome runtime bootstrap and style is based on the \"chrome\" layer and has the following major implementation classes:\n\n  * [ChromeMainDelegateCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_main_delegate_cef.h) - Implements the common process bootstrap logic.\n  * [ChromeContentClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_content_client_cef.h) - Implements the Content API callbacks that are common to all processes.\n  * [CefContext](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/context.h) - Represents the global CEF context in the browser process. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * [ChromeBrowserMainExtraPartsCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_main_extra_parts_cef.h) - Implements the browser process bootstrap logic.\n  * [ChromeContentBrowserClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_content_browser_client_cef.h) - Implements the Content API callbacks for the browser process.\n  * [ChromeBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n  * [ChromeContentRendererClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/chrome/chrome_content_renderer_client_cef.h) - Implements the Content API callbacks for the render process.\n  * [CefBrowserImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/browser_impl.h) - Implements the CefBrowser interface in the render process. Provides the glue code and implements interfaces for communicating with the RenderView.\n  * [ChromeBrowserDelegate](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_delegate.h) - Interface injected into Chrome's [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) object (via [patch files](https://github.com/chromiumembedded/cef/blob/master/patch/README.txt)) to support callbacks into CEF code.\n  * [ChromeBrowserFrame](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h) - Widget for a Views-hosted Chrome browser.\n\nAn overview of the Chrome Browser object model is also available [here](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h).","isInternal":false,"tokens":4964,"sizeBytes":22812},{"name":"README.md","path":"tools/cefbuilds/README.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/cefbuilds/README.md","title":"cefbuilds Documentation","category":"plugin-manifest","format":"markdown","content":"# CEF Builds JSON Tools\n\nTools for generating and maintaining the JSON index files used by the\n[CEF Builds](https://cef-builds.spotifycdn.com/index.html) CDN and the CEF\ninstaller.\n\n## Files\n\n### Core libraries\n\n- **`cef_json_builder.py`** — Builds and maintains the master `index.json` file\n  that contains the full catalog of CEF binary distributions across all\n  platforms, versions, and channels. Handles file metadata (name, size, sha1,\n  last_modified), Chromium version mapping, and sandbox compatibility hashes.\n\n- **`cef_installer_builder.py`** — Generates installer-optimized CDN query files\n  from a populated `cef_json_builder` instance. Produces lightweight JSON files\n  designed for efficient HTTP HEAD timestamp checks by the CEF installer.\n\n### Data files\n\n- **`revoked.json`** — Manually maintained list of revoked CEF versions. Revoked\n  versions are excluded from all installer-generated JSON output. The installer\n  also fetches this file from the CDN and refuses to install any listed version.\n\n### Examples and tests\n\n- **`cef_json_builder_example.py`** — Example script demonstrating\n  `cef_json_builder` usage. Creates and updates a local `index.json` with fake\n  file data.\n\n- **`cef_json_builder_test.py`** — Unit tests for `cef_json_builder`.\n\n- **`cef_installer_builder_test.py`** — Unit tests for `cef_installer_builder`.\n\n## CDN file formats\n\n### Master index\n\n- **`index.json`** — Full data index of all CEF binary distributions. Generated\n  by `cef_json_builder`. Keyed by platform, with version records sorted\n  newest-first by file last_modified timestamp.\n\n### Installer query files\n\nGenerated by `cef_installer_builder` from the master index:\n\n- **`stable.txt`** — Current stable milestone number (e.g., `137`).\n\n- **`{milestone}.json`** (e.g., `137.json`) — Newest build per platform for a\n  given milestone. Used by the installer to check if an update is available.\n\n- **`{milestone}_{platform}.json`** (e.g., `137_windows64.json`) — All builds\n  for a milestone+platform combination, sorted newest-first.\n\n- **`{abi_hash}_{platform}.json`** (e.g., `abc123def4567890_windows64.json`) —\n  All builds compatible with a given ABI hash and platform across all milestones,\n  sorted newest-first. Windows platforms only (tied to `chrome_elf.dll` /\n  Chromium sandbox ABI).\n\n## Concepts\n\n### Platforms\n\nSupported platforms: `linux32`, `linux64`, `linuxarm`, `linuxarm64`,\n`macosarm64`, `macosx64`, `windows32`, `windows64`, `windowsarm64`.\n\n### Distribution types\n\nEach version may have files of these types: `standard`, `minimal`, `client`,\n`tools`, `release_symbols`, `debug_symbols`, `signed`.\n\nThe `signed` type contains code-signed archives with catalog files, used by the\ninstaller for verified installation.\n\n### Channels\n\nVersions belong to either the `stable` or `beta` channel.\n\n### Version formats\n\n- **New-style**: `137.3.5+g62d140e+chromium-137.0.7204.6`\n  - Short version: `137.3.5` (everything before the first `+`)\n  - Milestone: `137` (major version number)\n- **Old-style**: `3.2704.1414.g185cd6c` (predates the installer format)\n\n### ABI hash (`sandbox_compat`)\n\nA 16-character hex string identifying the Windows sandbox ABI compatibility\nlevel. Derived from `cef_api_versions.json` on GitHub. Versions sharing the same\nABI hash can use the same `chrome_elf.dll` and are interchangeable from the\nsandbox's perspective.\n\n### Revocation\n\nThe `revoked.json` file lists versions that must not be installed. When passed\nto `cef_installer_builder`, revoked versions are automatically excluded from\nall generated output. The installer also fetches this file from the CDN at\nruntime and refuses to install any listed version.\n\nEntries can revoke a single version or a range of versions:\n\n```json\n{\n  \"revoked_versions\": [\n    {\n      \"version\": \"137.1.0\",\n      \"reason\": \"CVE-2024-XXXXX: critical sandbox escape\",\n      \"revoked_at\": \"2024-01-15T00:00:00Z\"\n    },\n    {\n      \"version_min\": \"138.0.0\",\n      \"version_max\": \"138.2.99\",\n      \"reason\": \"CVE-2024-YYYYY: affects all 138.0–138.2 builds\",\n      \"revoked_at\": \"2024-02-01T00:00:00Z\"\n    }\n  ]\n}\n```\n\n**Single version** (point revocation):\n- `version` — Short version string (e.g., `137.1.0`).\n\n**Version range** (inclusive):\n- `version_min` — Inclusive lower bound (e.g., `138.0.0`).\n- `version_max` — Inclusive upper bound (e.g., `138.2.99`).\n\n**Common fields:**\n- `reason` — Human-readable explanation (CVE ID, bug reference, etc.).\n- `revoked_at` — ISO 8601 timestamp of when the revocation was added.\n\nA single-version entry using `version` is equivalent to setting both\n`version_min` and `version_max` to the same value. If both `version` and\n`version_min`/`version_max` are present, the range fields take precedence.\n\n## Running tests\n\n```bash\ncd cef/tools/cefbuilds\npython3 -m unittest cef_json_builder_test -v\npython3 -m unittest cef_installer_builder_test -v\n```\n","isInternal":false,"tokens":1266,"sizeBytes":4909},{"name":"README.md","path":"tools/clang/README.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/clang/README.md","title":"clang Documentation","category":"plugin-manifest","format":"markdown","content":"# CEF Clang Tools\n\nThis directory contains clang-based tools for CEF code modernization and refactoring.\n\n## Tools\n\n### cef_cpp_rewriter\n\nA clang AST-based rewriter tool for automating C++20 modernization of CEF code.\n\n**Supported transformations:**\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for complete documentation of all transformations, command-line flags, and examples.\n\n## Prerequisites\n\n- Chromium checkout with CEF\n- **Python 3.10+** (Chromium's build scripts require it)\n- ~30 minutes for initial clang bootstrap\n\n**Note:** CEF is a separate git repository within chromium/src. Chromium's clang\ntool scripts (`run_tool.py`, `test_tool.py`, `apply_edits.py`) use git commands\nthat don't work across repository boundaries. This directory provides CEF-specific\nreplacements: `run_tool.py`, `test_tool.py`, and `apply_edits.py`.\n\n### Python Version\n\nmacOS ships with Python 3.9 which is too old. Install Python 3.12 via Homebrew:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\npython3 --version  # Should show 3.12.x\n```\n\nAdd the export line to `~/.zshrc` to make it permanent.\n\n## Quick Start\n\n### Initial Setup (one-time, ~30 minutes)\n\n```bash\n# From chromium/src directory\n./cef/tools/clang/scripts/build_clang_rewriter.sh\n```\n\nThis will:\n\n1. Create a symlink from `tools/clang/cef_cpp_rewriter` to the CEF tool\n2. Bootstrap clang with the tool (~30 minutes)\n\n**Warning:** The clang bootstrap updates `third_party/llvm-build/`, which will\ninvalidate all existing Chromium/CEF build directories and trigger a full\nrebuild the next time you build. Plan accordingly.\n\n### Running the Tool\n\n```bash\n# Create a build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool\ncp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run the tool on CEF code (all transformations enabled by default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--structured-bindings --contains=false\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Or run on all CEF files (omit path arguments)\n# python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool\n\n# Process and apply the edits\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\n**Examples:**\n```bash\n# Run only iterator-loops transformation\n--tool-args=\"--only=iterator-loops\"\n\n# Run only contains and structured-bindings\n--tool-args=\"--only=contains,structured-bindings\"\n\n# Disable specific transformation (all others still run)\n--tool-args=\"--contains=false\"\n```\n\n### Incremental Rebuilds\n\nAfter modifying `CefCppRewriter.cpp`, rebuild quickly with:\n\n```bash\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Do not re-run `build_clang_rewriter.sh`** - it rebuilds everything from scratch.\n\n## Testing\n\n```bash\n# Run tool tests\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n## Compatibility\n\nCEF targets C++20. See [TRANSFORMS.md](TRANSFORMS.md) for minimum toolchain versions.\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory\n./cef/tools/clang/scripts/package_standalone.sh /path/to/target\n\n# This creates:\n# /path/to/target/\n# ├── bin/cpp_rewriter           # The tool binary\n# ├── lib/clang/<version>/       # Bundled clang headers\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\nThe standalone distribution is self-contained and includes bundled clang headers\nso it works without requiring a matching system clang installation.\n\n**Usage on any CMake project:**\n```bash\ncd my-project\n\n# Generate compile_commands.json (requires Ninja or Makefiles generator)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Run the rewriter\n/path/to/target/scripts/run_rewriter.py -p build src/ \\\n  | /path/to/target/scripts/apply_edits.py --base-dir build\n```\n\nSee `standalone/README.md` for complete standalone usage documentation.\n\n## Directory Structure\n\n```\ncef/tools/clang/\n├── cef_cpp_rewriter/\n│   ├── CMakeLists.txt\n│   ├── CefCppRewriter.cpp\n│   ├── OutputHelper.h\n│   ├── OutputHelper.cpp\n│   └── tests/\n│       ├── contains-original.cc\n│       ├── contains-expected.cc\n│       ├── contains-negative-original.cc\n│       ├── contains-negative-expected.cc\n│       ├── disallow-copy-original.cc\n│       ├── disallow-copy-expected.cc\n│       ├── disallow-copy-negative-original.cc\n│       ├── disallow-copy-negative-expected.cc\n│       ├── structured-bindings-original.cc\n│       ├── structured-bindings-expected.cc\n│       ├── structured-bindings-negative-original.cc\n│       ├── structured-bindings-negative-expected.cc\n│       ├── iterator-loops-original.cc\n│       ├── iterator-loops-expected.cc\n│       ├── iterator-loops-negative-original.cc\n│       └── iterator-loops-negative-expected.cc\n├── scripts/\n│   ├── apply_edits.py            # Applies edits (no git dependency)\n│   ├── build_gen_targets.sh      # Build CEF-related gen targets only\n│   ├── build_clang_rewriter.sh   # Bootstrap clang with the tool\n│   ├── package_standalone.sh     # Package for standalone use\n│   ├── process_edits.py          # Adds markers, deduplicates edits\n│   ├── run_tool.py               # Run tool on CEF files\n│   └── test_tool.py              # CEF-specific test harness\n├── standalone/\n│   ├── README.md                 # Standalone usage documentation\n│   └── run_rewriter.py           # Standalone wrapper script\n├── CLAUDE.md\n├── README.md\n└── TRANSFORMS.md                 # Transformation documentation\n```\n\n## Maintenance\n\nThis tool is not regularly tested. It may need updates when:\n\n| Trigger | Likely Fix |\n|---------|------------|\n| Chromium updates `tools/clang/` infrastructure | Update `CMakeLists.txt`, check `build.py` flags |\n| LLVM/Clang API changes | Update AST matcher syntax, check deprecations in Clang doxygen |\n| CEF adopts C++23 | Add `flat_map`/`flat_set` container types to matcher |\n| Build fails after Chromium update | Compare with current `tools/clang/ast_rewriter/` example |\n\n### Diagnosing Build Failures\n\nIf the tool fails to build after a Chromium update:\n\n1. Check if `ast_rewriter` still exists and builds:\n    ```bash\n    python3 tools/clang/scripts/build.py --bootstrap --extra-tools ast_rewriter\n    ```\n\n2. Compare CMakeLists.txt with the current ast_rewriter version:\n    ```bash\n    diff cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt tools/clang/ast_rewriter/CMakeLists.txt\n    ```\n\n3. Check for API changes in Clang's AST matchers (review Clang release notes)\n\n### Cleanup\n\nAfter running the tool, you may want to remove the symlink:\n\n```bash\nrm tools/clang/cef_cpp_rewriter  # Removes symlink only, not CEF source\n```\n\n## Resources\n\n- Chromium clang tool documentation: `docs/clang_tool_refactoring.md`\n- Chromium example: `tools/clang/ast_rewriter/`\n- [AST Matcher Reference](https://clang.llvm.org/docs/LibASTMatchersReference.html)\n- [LibTooling Tutorial](https://clang.llvm.org/docs/LibASTMatchersTutorial.html)\n","isInternal":false,"tokens":2181,"sizeBytes":8820},{"name":"README.md","path":"tools/clang/standalone/README.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/clang/standalone/README.md","title":"standalone Documentation","category":"plugin-manifest","format":"markdown","content":"# C++ Rewriter Tool\n\nA clang-based AST rewriter for C++20 modernization. This tool performs\ntype-aware code transformations that cannot be done with simple regex,\nsuch as replacing `map.find(x) != map.end()` with `map.contains(x)`.\n\n## Distribution Contents\n\nThis is a self-contained distribution that includes everything needed to run:\n\n```\ncpp_rewriter/\n├── bin/\n│   └── cpp_rewriter           # The clang-based rewriter tool\n├── lib/\n│   └── clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n│       └── include/\n├── scripts/\n│   ├── run_rewriter.py        # Main wrapper script\n│   ├── apply_edits.py         # Applies generated edits to files\n│   └── process_edits.py       # Deduplicates and formats edits\n└── README.md\n```\n\nThe bundled `lib/clang/` headers are automatically detected and used by the\nwrapper script, so the tool works without requiring a matching system clang.\n\n## Prerequisites\n\n- A C++ project with a `compile_commands.json` file\n- Python 3.6+\n\n## Generating compile_commands.json\n\nThe tool requires a compilation database to understand your project's\nbuild configuration. Here's how to generate one for common build systems:\n\n### CMake\n\n**Important:** `CMAKE_EXPORT_COMPILE_COMMANDS` only works with **Makefile**\nand **Ninja** generators. It does NOT work with Xcode or Visual Studio generators.\n\n```bash\n# Using Ninja (recommended)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Using Unix Makefiles\ncmake -G \"Unix Makefiles\" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# compile_commands.json is now in build/\n```\n\nIf you normally use Xcode/Visual Studio, create a separate build directory\njust for tooling:\n\n```bash\n# Keep your Xcode build, add a parallel Ninja build for tools\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build-tools\n# Use build-tools/compile_commands.json with the rewriter\n```\n\n### Meson\n\n```bash\nmeson setup build\n# compile_commands.json is automatically generated in build/\n```\n\n### Bear (for Make-based projects)\n\n```bash\n# Install Bear: https://github.com/rizsotto/Bear\nbear -- make\n# compile_commands.json is generated in current directory\n```\n\n### Ninja\n\n```bash\nninja -C build -t compdb > build/compile_commands.json\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Run on all files in compile_commands.json\n./scripts/run_rewriter.py -p /path/to/build | ./scripts/apply_edits.py --base-dir /path/to/build\n\n# Run on specific source directories only\n./scripts/run_rewriter.py -p build src/ include/ | ./scripts/apply_edits.py --base-dir build\n```\n\n### Filter by Path Pattern\n\nUse `--path-filter` with a substring to process only matching files:\n\n```bash\n# Only process files containing \"src/core/\" in their path\n./scripts/run_rewriter.py -p build --path-filter \"src/core/\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Disable Specific Transformations\n\n```bash\n# Disable structured bindings transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--structured-bindings=false\" | ./scripts/apply_edits.py --base-dir build\n\n# Run only the .contains() transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--only=contains\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Verbose Output\n\n```bash\n# Show progress\n./scripts/run_rewriter.py -p build -v src/ 2>&1 | tee /tmp/edits.txt\n./scripts/apply_edits.py --base-dir build < /tmp/edits.txt\n```\n\n## Available Transformations\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nAll transformations are enabled by default. Use `--flag=false` to disable specific ones,\nor `--only=<list>` to run only specific transformations.\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags,\nbefore/after examples, supported containers, and edge cases.\n\n## Troubleshooting\n\n### \"compile_commands.json not found\"\n\nMake sure you've generated the compilation database. See the\n\"Generating compile_commands.json\" section above.\n\n### \"No files found matching...\"\n\n- Check that the path filter matches your file paths\n- Use `-v` for verbose output to see which files are being processed\n- Try running without a path filter first\n\n### Transformations not applying\n\n- The tool only transforms code, not macro expansions\n- Some patterns may not match due to unusual formatting\n- Use `-v` to see error messages from the tool\n\n## Compatibility\n\nThe transformed code uses C++20 features. See [TRANSFORMS.md](TRANSFORMS.md) for\nminimum compiler requirements.\n\n## Building from Source\n\nThis tool is built as part of the CEF (Chromium Embedded Framework) project.\nSee the CEF repository for build instructions.\n","isInternal":false,"tokens":1130,"sizeBytes":4741},{"name":"README.md","path":"tools/claude/README.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/claude/README.md","title":"claude Documentation","category":"plugin-manifest","format":"markdown","content":"# Tools and Detailed Instructions for CEF Development\n\nThis directory contains tools and detailed instructions for using coding\nagents to assist with CEF (Chromium Embedded Framework) development. Use these\nguides with models that benefit from explicit workflows, examples, and\nverification steps, including Claude Opus 4.x and GPT Terra.\n\nThe guides were originally written for Claude Code and retain their `CLAUDE_*`\nfilenames. Other coding agents can use them directly; adapt any Claude-specific\nsetup or file attachment syntax to your agent. For GPT Sol or other frontier\nmodels that work well with concise instructions, see the\n[GPT guides](../gpt/README.md) for concise patch and build instructions and\nexample prompts. For other tasks, newer frontier models can often discover the\nrelevant details themselves, using the detailed instruction files here as\nreference material when needed.\n\n***\n[TOC]\n***\n\n## Quick Navigation\n\n**Are you updating CEF to a new Chromium version?**\n\n→ See [CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md) for the complete workflow:\n\n- Fixing patches that fail to apply\n- Fixing build errors from API changes\n- Using analyzer scripts and verification tools\n\n**Are you developing a CEF application using a binary distribution?**\n\n→ See [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md) for implementing features:\n\n- Adding custom URL schemes\n- JavaScript-to-C++ communication\n- Network request interception\n- Popup window customization\n\n**Are you writing or debugging CEF unit tests?**\n\n→ See [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md) for working with ceftests:\n\n- Running existing unit tests\n- Creating new tests for CEF features\n- Debugging test failures and flakiness\n- Using TestHandler, RoutingTestHandler, and TestServer\n\n**Are you developing libcef internals (CEF implementation code)?**\n\n→ See [CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md) for libcef development patterns:\n\n- Adding new CEF APIs with proper versioning\n- Implementing WebContentsDelegate callbacks\n- Working with Chrome and Alloy browser styles\n- Finding and fixing NOTIMPLEMENTED() stubs\n\n**Are you syncing CEF base headers with Chromium?**\n\n→ See [CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md) for synchronizing `cef/include/base/` headers:\n\n- CEF-specific modifications (namespaces, includes, platform macros)\n- Files to sync vs files to preserve\n- Handling C++23 reverts\n- Step-by-step sync process\n\n**Are you cherry-picking commits from upstream CEF?**\n\n→ See [CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md) for cherry-picking commits that include patch files:\n\n- Extracting and applying source file changes from patches\n- Resaving patches with correct index hashes\n- Handling multiple patch files per commit\n- Recovery when things go wrong\n\n**Are you applying a Chromium commit to CEF as a patch?**\n\n→ See [CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md) for creating or updating CEF patches from Chromium commits:\n\n- Creating new patch files and adding to patch.cfg\n- Adding changes to existing patch files\n- Handling version differences between Chromium versions\n- Verifying patches can be reverted and reapplied\n\n**Are you improving unit test coverage?**\n\n→ See [CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md) for running and analyzing code coverage:\n\n- Human prerequisites for setting up coverage builds\n- Building and running tests with coverage instrumentation\n- Analyzing coverage reports to identify gaps\n- Workflow for improving function and line coverage\n\n## Files in This Directory\n\n### Documentation\n\n- **[CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md)** - Complete guide for updating CEF to new Chromium versions\n- **[CLAUDE.md.in](CLAUDE.md.in)** - Template for root CLAUDE.md (copied by setup_claude.py)\n- **[CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md)** - Instructions for syncing CEF base headers with Chromium\n- **[CLAUDE_BUILD_INSTRUCTIONS.md](CLAUDE_BUILD_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing build errors\n- **[CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md)** - Instructions for cherry-picking commits from upstream CEF that include patch files\n- **[CLAUDE_CLIENT_INSTRUCTIONS.md](CLAUDE_CLIENT_INSTRUCTIONS.md)** - Detailed instructions for Claude agents implementing features in CEF applications\n- **[CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md)** - Instructions for running and analyzing code coverage\n- **[CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md)** - Detailed instructions for Claude agents developing libcef internals (API versioning, WebContentsDelegate)\n- **[CLAUDE_PATCH_INSTRUCTIONS.md](CLAUDE_PATCH_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing patch failures\n- **[CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md)** - Instructions for applying Chromium commits to CEF as new or existing patches\n- **[CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md)** - Detailed instructions for Claude agents creating and running CEF unit tests\n- **[CLAUDE_WIKI_INSTRUCTIONS.md](CLAUDE_WIKI_INSTRUCTIONS.md)** - Bitbucket wiki formatting guidelines for Claude agents\n- **[CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md)** - Complete guide for CEF client application development\n- **[README.md](README.md)** - This file\n\n### Python Tools\n\n- **[analyze_build_output.py](analyze_build_output.py)** - Analyze and format ninja build output with error index\n- **[analyze_coverage_output.py](analyze_coverage_output.py)** - Analyze LLVM coverage reports and identify coverage gaps\n- **[analyze_patch_output.py](analyze_patch_output.py)** - Analyze and format `patch_updater.py` output with file movement detection\n- **[patch_utils.py](patch_utils.py)** - Shared utilities for patch analysis tools (file movement detection)\n- **[verify_patch.py](verify_patch.py)** - Verify that regenerated patches include all changes from reject files\n- **[format_wiki.py](format_wiki.py)** - Apply Bitbucket wiki formatting guidelines to markdown files (supports wildcards; also integrated into `../fix_style.py`)\n\n### Test Files\n\n- **[analyze_build_output_test.py](analyze_build_output_test.py)** - Unit tests for analyze_build_output.py\n- **[analyze_coverage_output_test.py](analyze_coverage_output_test.py)** - Unit tests for analyze_coverage_output.py\n- **[analyze_patch_output_test.py](analyze_patch_output_test.py)** - Unit tests for analyze_patch_output.py\n- **[patch_utils_test.py](patch_utils_test.py)** - Unit tests for patch_utils.py\n- **[verify_patch_test.py](verify_patch_test.py)** - Unit tests for verify_patch.py\n- **[format_wiki_test.py](format_wiki_test.py)** - Unit tests for format_wiki.py\n\n## Common Setup\n\nFor Chromium update workflows, run the setup script:\n\n```bash\ncd chromium/src/cef/tools\npython3 setup_claude.py\n```\n\nThis copies `CLAUDE.md.in` to the project root as `chromium/src/CLAUDE.md`, enabling Claude Code to understand the Chromium/CEF codebase structure.\n\n## Formatting Files\n\nThe `fix_style.py` tool in `//cef/tools/` formats C/C++, Python, and Markdown files:\n\n```bash\n# From chromium/src/cef/tools directory:\n\n# Format single markdown file\npython3 fix_style.py claude/CLAUDE_TEST_INSTRUCTIONS.md\n\n# Format all CLAUDE instruction files\npython3 fix_style.py claude/CLAUDE_*.md\n\n# Format all markdown files in claude directory\npython3 fix_style.py claude/*.md\n\n# Format all staged files (including markdown)\npython3 fix_style.py staged\n```\n\nThe markdown formatter applies [Bitbucket wiki formatting guidelines](CLAUDE_WIKI_INSTRUCTIONS.md) (blank lines before lists, 4-space indentation, etc.).\n\n## Tips for Working with Claude Code\n\nThese tips apply to both Chromium updates and client development:\n\n### 1. Provide Context\n\nAlways include relevant version numbers or distribution details:\n\n**For Chromium updates:**\n```\nOld version: 139.0.7258.0\nNew version: 140.0.7339.0\n```\n\n**For client development:**\n```\nCEF binary distribution: cef_binary_142.0.10+g29548e2+chromium-142.0.7444.135_macosarm64\n```\n\n### 2. Attach Relevant Files\n\nUse `@filename` to attach files Claude should read:\n\n- `@cef/tools/claude/patch_analysis.txt` - Analyzed patch output\n- `@cef/tools/claude/build_analysis.txt` - Analyzed build output\n- `@cef/tools/claude/CLAUDE_CHERRY_PICK_INSTRUCTIONS.md` - Cherry-picking upstream commits\n- `@cef/tools/claude/CLAUDE_CLIENT_INSTRUCTIONS.md` - Client development guide\n- `@cef/tools/claude/CLAUDE_SRC_PATCH_INSTRUCTIONS.md` - Applying Chromium commits as patches\n- `@cef/tools/claude/CLAUDE_TEST_INSTRUCTIONS.md` - CEF unit testing guide\n\n**Tip:** In large directory structures like `chromium/src`, the `@` syntax can be slow. Use `//` syntax for workspace-relative paths instead (e.g., `//cef/tools/claude/patch_analysis.txt`).\n\n### 3. Let Claude Work Systematically\n\nDon't interrupt mid-stream unless necessary. Claude will:\n\n- Create TODO lists\n- Work through items one by one\n- Report progress regularly\n- Ask for help when stuck\n\n### 4. Use Incremental Prompts\n\nFor large tasks, you can guide Claude incrementally:\n\n**For Chromium updates:**\n```\n1. \"Start fixing patches using @CLAUDE_PATCH_INSTRUCTIONS.md\"\n2. [Claude works for a while]\n3. \"Good progress. Continue with the remaining patches.\"\n4. [Claude finishes]\n5. \"Now let's fix build errors using @CLAUDE_BUILD_INSTRUCTIONS.md\"\n```\n\n**For unit testing:**\n```\n1. \"Create tests for the new feature using @CLAUDE_TEST_INSTRUCTIONS.md\"\n2. [Claude creates tests]\n3. \"Run the tests and fix any failures\"\n4. [Claude debugs and fixes]\n5. \"Good, now verify they work in both Chrome and Alloy styles\"\n```\n\n### 5. Ask for Summaries\n\nAfter a session:\n```\nPlease summarize all the changes you made, organized by category.\n```\n\nClaude can provide a detailed summary for documentation or commit messages.\n\n### 6. Use the Analyzers Proactively\n\nFor Chromium updates, run the analyzers yourself first to understand the scope:\n\n**For patches:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_patch_output.py patch_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > patch_analysis.txt\n```\n\n**For build errors:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_build_output.py build_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > build_analysis.txt\n```\n\nThen share the analysis files with Claude.\n\n## Getting Help\n\n### For Issues with Tools\n\n- Check the guide files and instruction files listed above for usage examples\n- Check analyzer script help: `python3 analyze_patch_output.py --help`\n\n### For Issues with CEF\n\n- CEF wiki: https://github.com/chromiumembedded/cef/blob/master/docs/README.md\n- CEF forums: https://magpcss.org/ceforum/\n- CEF issue tracker: https://github.com/chromiumembedded/cef/issues\n\n### For Issues with Claude Code\n\n- Claude Code documentation: https://docs.claude.com/claude-code\n- Improve prompts with more context and specific examples\n- Break large tasks into smaller, more manageable pieces\n\n## Contributing\n\nIf you improve these tools or instructions:\n\n1. Test with a real Chromium update, client development task, or unit testing workflow\n2. Document what you changed and why\n3. Update the appropriate guide ([CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md), [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md), or [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md))\n4. Share improvements with the CEF community\n\n## License\n\nThese tools are part of the CEF project and follow the same license as CEF (BSD license).\n","isInternal":false,"tokens":2782,"sizeBytes":11662},{"name":"README.md","path":"tools/debug/ax_viewport_collapse/README.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/debug/ax_viewport_collapse/README.md","title":"ax_viewport_collapse Documentation","category":"plugin-manifest","format":"markdown","content":"# ax_viewport_collapse Debug Tools\n\nManual verification tools for the `ax_viewport_collapse` CefBrowserSettings feature.\nThese connect to a running cefclient via CDP to inspect the accessibility tree.\n\n## Prerequisites\n\n```\npython3 -m pip install websocket-client\n```\n\n## Usage\n\n### 1. Launch cefclient with remote debugging\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\n```\n\nThe `--ax-viewport-collapse` flag maps to `CefBrowserSettings.ax_viewport_collapse = STATE_ENABLED` in cefclient.\n\nTo load the test page directly:\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse --url=file:///<path>/test_viewport_collapse.html\n```\n\n### 2. Run the verification script\n\n```\npython3 verify_viewport_collapse.py\n```\n\nOr navigate to a URL first:\n\n```\npython3 verify_viewport_collapse.py --url https://example.com\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `--host` | CDP host (default: `127.0.0.1`) |\n| `--port` | CDP port (default: `9222`) |\n| `--url` | Navigate to URL before fetching tree |\n| `--raw` | Print full JSON response instead of summary |\n\n### Comparing with/without collapse\n\nRun two cefclient instances on different ports:\n\n```\ncefclient.exe --cache-path=<path1> --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\ncefclient.exe --cache-path=<path2> --remote-debugging-port=9223 --remote-allow-origins=*\n```\n\n```\npython3 verify_viewport_collapse.py --port 9222 --raw > with.json\npython3 verify_viewport_collapse.py --port 9223 --raw > without.json\ndiff with.json without.json\n```\n\n### Expected output (with collapse enabled)\n\n```\nAX Tree Summary\n============================================================\nTotal nodes returned:  77\n  Ignored:             3\n  Full (with children):70\n  Summary (collapsed): 4\n\nCollapsed summary nodes (off-screen landmarks/headings):\n------------------------------------------------------------\n  region: \"Content preferences\"\n  region: \"Audio quality\"\n  region: \"Display\"\n  region: \"Storage\"\n```\n\nOff-screen landmark sections appear as leaf nodes with role + name only. In-viewport nodes are fully serialized with children.\n\n## Files\n\n- `verify_viewport_collapse.py` — CDP script that calls `Accessibility.getFullAXTree()` and prints a summary or raw JSON\n- `test_viewport_collapse.html` — Test page with 6 landmark sections, 2 in viewport and 4 pushed off-screen by a spacer\n","isInternal":false,"tokens":617,"sizeBytes":2463},{"name":"README.md","path":"tools/gpt/README.md","rawUrl":"https://raw.githubusercontent.com/chromiumembedded/cef/HEAD/tools/gpt/README.md","title":"gpt Documentation","category":"plugin-manifest","format":"markdown","content":"# GPT Instructions for CEF Updates\n\nUse these guides when asking a coding agent to update CEF patches or fix build\nerrors during a Chromium update. The GPT guides give Sol a short overview of\nwhat to do and how to verify the result. They link to the existing Claude\nguides for detailed commands, examples, and troubleshooting.\n\n## Choosing a model\n\n| Model | Starting effort | Guides to use |\n| --- | --- | --- |\n| GPT-6.1 Sol | Low | The GPT guides in this directory |\n| GPT-5.6 Terra | Choose for your task | The Claude guides in `cef/tools/claude/` |\n\nFor Sol, start with low effort and use the Sol examples below. The agent can\nconsult the linked Claude guides as it works. For Terra, use the Terra examples,\nwhich point directly to the detailed Claude guides. Those guides work with\nother models despite their filenames.\n\nSelect the model and effort in your coding agent before sending the prompt.\nThe instruction files describe the work; model selection is a separate setting.\n\nThese recommendations are a starting point for trying the workflows on real\nupdates. Adjust the GPT model and reasoning effort to balance speed and cost\nwhile meeting the same completion checks. Check whether the agent covers every\nfailed file, preserves CEF behavior, and saves source fixes into the patches.\nIf Sol gets stuck on a particular issue or cannot explain why a behavioral\nchange is correct, try that issue again at medium effort. When comparing speed\nand cost, include any follow-up work needed to correct the result.\n\n## Getting started\n\nBefore launching the agent, use the existing Chromium update guide to prepare\nyour checkout and the analysis for the phase you're working on:\n\n1. Review the [complete update workflow](../claude/CHROMIUM_UPDATE.md#complete-update-workflow)\n   for the order of checkout updates, patch repairs, builds, and testing.\n2. Check the [prerequisites](../claude/CHROMIUM_UPDATE.md#prerequisites) and\n   [setup](../claude/CHROMIUM_UPDATE.md#setup): you'll need a Chromium checkout\n   with CEF integration, Python 3, and the appropriate build configuration.\n   The `setup_claude.py` step installs context for Claude Code; it is not a\n   prerequisite for using the GPT prompts.\n3. For patch repairs, follow [Phase 1: Fixing Patches](../claude/CHROMIUM_UPDATE.md#phase-1-fixing-patches)\n   to capture `patch_updater.py` output and generate `patch_analysis.txt` with\n   your old and new Chromium versions. Then use the patch prompt below.\n4. Once the patches apply cleanly, follow [Phase 2: Fixing Build Errors](../claude/CHROMIUM_UPDATE.md#phase-2-fixing-build-errors)\n   to capture a build of your chosen target and generate `build_analysis.txt`.\n   Then use the build prompt below.\n\nStart your coding agent from the `chromium/src` checkout root. Copy one of the\ncomplete prompts below, then replace the Chromium versions and analysis path\nwith yours. For a build task, also set your output directory and build target.\nAll paths in the prompts are relative to `chromium/src`.\n\nUse the analysis files produced by the existing tools in `cef/tools/claude/`:\n\n- `patch_analysis.txt` lists failed patches and files.\n- `build_analysis.txt` lists build errors and points to the relevant sections\n  of `build_output.txt`.\n\nThe build examples include permission to fix Chromium files outside `cef/`\nwhen custom CEF patches cause their build failures. Keep that instruction if\nit applies to your update: it tells the agent to save those fixes into the\nassociated CEF patches and overrides the detailed build guide's usual scope.\n\n## Example prompts for Sol at low effort\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/gpt/GPT_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. Fix those build\nerrors and re-save the associated CEF patch files using\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n\n## Example prompts for Terra\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. You should also\nfix those build errors and re-save the associated CEF patch files using\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md. This extends the build\nguide's default restriction to files under cef.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n","isInternal":false,"tokens":1450,"sizeBytes":6119}],"systemPromptSnippet":"<yakaai_skills repo=\"chromiumembedded/cef\">\n<!-- File: tools/AGENTS.md (Tokens: ~1130 | Category: root-instruction) -->\n# CEF Tools Contributor and Agent Guidelines\n\nThis file applies to `//cef/tools` and its descendants.\n\n## Generator inventory and coverage\n\n- Every direct-child, non-test `make_*.py` generator must have a matching\n  `make_*_test.py` module.\n- `make_generator_inventory_test.py` enforces the direct-child inventory. When\n  adding or removing a generator, update its expected count intentionally and\n  keep nested generators, helpers, and existing tests out of the inventory.\n- Exercise every top-level generator function through at least one successful\n  test. Cover meaningful explicit error branches, writer behavior, and the\n  generator's CLI style; do not treat filename coverage as function coverage.\n- Use standard-library `unittest`, `tempfile`, and `unittest.mock`. Run from the\n  CEF root:\n\n  ```sh\n  python3 -m unittest discover -s tools -p '*_test.py'\n  python3 -m unittest discover -s tools -p 'make_example_test.py' -v\n  ```\n\n- Run the complete suite twice for generator-wide work. These modules share\n  parser state, so the second run detects ordering and cleanup leaks.\n\n## Hermetic fixtures and goldens\n\n- Put deterministic inputs and reviewed goldens under\n  `tools/testdata/make_generators/`; use `generator_test_util.py` for shared\n  fixture, manifest, archive, and CLI helpers.\n- Mock or fix time, year, Git metadata, versions, platforms, environment\n  variables, external commands, and formatter results when they affect output.\n- Goldens must originate from a reviewed baseline, never from ignored\n  working-tree output, and tests must not contain an auto-update path.\n- Use inline expectations for small output and reviewed full-file goldens for\n  larger generated C/C++ content. Add targeted assertions that explain the\n  behavior protected by a golden.\n- Prove that customized CppToC/CToCpp bodies survive regeneration, source\n  fixtures are not modified, and relevant paths work when they contain spaces.\n\n## Writer contracts\n\n- Test every writer on its first generation and an identical second\n  generation.\n- For `write_file_if_changed`, assert changed/unchanged returns and preserved\n  mtime. For unconditional writers, assert stable bytes across rewrites.\n- Multi-output writers must report a change when any output changes. Test\n  repairs where only one output was corrupted.\n- Pre-publication failures must leave outputs missing or unchanged. Characterize\n  partial I/O-failure output before changing it; atomic publication is a\n  separate behavior change.\n\n## CLI contracts\n\n- Cover invalid status, stdout, stderr, and partial artifacts, plus successful\n  stdout, single-file, multi-output, argparse, and distribution CLI styles.\n- If a generator function returns metadata with its content, such as\n  `(content, customized)`, unpack the result at the CLI boundary and write only\n  the string content. Do not change the underlying generator return contract\n  merely to fix a CLI.\n- Assert progress messages exactly when callers may depend on them, and return\n  explicit nonzero statuses for rejected invocations.\n\n## Parser and module state\n\n- Restore parser notification context and other module globals with\n  `try/finally`; add test cleanup so failing regressions cannot leak state.\n- Generator modules intended for reuse must be importable without parsing\n  arguments, exiting, mutating files, calling Git, or launching subprocesses.\n  Put orchestration in `main(argv=None)` and use a conventional guarded entry\n  point when refactoring for importability.\n\n## Output equivalence\n\n- Establish an exact pre-refactor baseline and keep testability refactors\n  separate from behavior fixes.\n- Testability refactors must preserve generated bytes, paths, ordering,\n  comments, whitespace, guards, encoding, newlines, modes, and symlink targets.\n- Compare fixes to the latest approved baseline while retaining the original\n  refactor baseline as an immutable reference.\n- Return-value, status, diagnostic, and CLI changes must not alter generated\n  files unless that is their documented purpose.\n- For translator changes, run a repository-scale comparison covering C API,\n  CppToC, CToCpp, wrapper, dylib, and GYPI outputs.\n- For distribution changes, compare the complete normalized tree. Compare\n  archive member paths, types, uncompressed bytes, and modes; normalize archive\n  timestamps only. Do not use raw archive-container hashes as equivalence.\n- Use the same Python interpreter as the recorded baseline. Python-version\n  differences can change comment wrapping and produce misleading byte deltas.\n\n## Bug-fix workflow\n\n- Reproduce a bug with a focused regression before changing production code.\n- Keep coverage/refactor checkpoints separate from behavior fixes so output\n  differences cannot be attributed to the wrong change.\n- Keep unrelated bugs independently reviewable. Closely related instances of\n  the same root cause may be grouped when explicitly requested.\n\n## Formatting and validation\n\n- From the CEF root, format only explicit changed Python paths:\n\n  ```sh\n  python3 tools/fix_style.py tools/make_example.py tools/make_example_test.py\n  ```\n\n- Inspect formatter output immediately. The formatter may rewrap unrelated\n  legacy code; revert that churn with targeted patches.\n- Compile every changed generator, helper, and test.\n- Run `git diff --check` and scan untracked files for trailing whitespace.\n- Re-run focused tests after formatting, then run the complete suite twice.\n\n<!-- File: tools/CLAUDE.md (Tokens: ~5 | Category: claude-rule) -->\n@AGENTS.md\n\n<!-- File: tools/clang/CLAUDE.md (Tokens: ~3024 | Category: anthropic-skill) -->\n# CEF Clang Tools - Claude Code Instructions\n\nThis file provides guidance to Claude Code when working with CEF clang tools.\n\n## Overview\n\nThe `cef_cpp_rewriter` tool is a clang AST-based rewriter for C++20 modernization.\nIt uses Clang's LibTooling and AST matchers to perform type-aware transformations\nthat cannot be done with simple regex.\n\n**Supported transformations:** `.contains()`, structured bindings, iterator loops,\nDISALLOW_COPY_AND_ASSIGN. See [TRANSFORMS.md](TRANSFORMS.md) for complete documentation.\n\n**Important:** CEF is a separate git repository within chromium/src. Chromium's\nclang tool scripts use git commands that don't work across repository boundaries.\nUse the CEF-specific scripts in `cef/tools/clang/scripts/` instead.\n\n## Key Files\n\n- `cef/tools/clang/cef_cpp_rewriter/CefCppRewriter.cpp` - Main tool implementation\n- `cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt` - Build configuration\n- `cef/tools/clang/scripts/build_clang_rewriter.sh` - Bootstrap script\n- `cef/tools/clang/scripts/package_standalone.sh` - Package for standalone use\n- `cef/tools/clang/standalone/` - Standalone distribution files\n- `cef/tools/clang/cef_cpp_rewriter/tests/` - Test cases\n\n## Prerequisites\n\n**Python 3.10+ required.** Chromium's build scripts use type union syntax that requires Python 3.10+. On macOS:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\n```\n\n## Development Workflow\n\n### Building the Tool\n\nAfter modifying `CefCppRewriter.cpp`:\n\n```bash\n# Fast incremental rebuild (~seconds)\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Never re-run `build_clang_rewriter.sh`** unless the build directory was deleted.\nIt rebuilds clang from scratch (~30 minutes).\n\n### Testing Matchers with clang-query\n\n```bash\nexport PATH=$PATH:third_party/llvm-build/Release+Asserts/bin\nclang-query /tmp/test.cc --\n```\n\n### Generating compile_commands.json for Manual Testing\n\nThe `test_tool.py` script generates this automatically, but for manual testing:\n\n```bash\n# macOS (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -isysroot $(xcrun --show-sdk-path) -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Linux (run from chromium/src)\nTEST_DIR=$(pwd)/cef/tools/clang/cef_cpp_rewriter/tests\ncat > $TEST_DIR/compile_commands.json << EOF\n[{\"directory\": \"$TEST_DIR\", \"command\": \"clang++ -std=c++20 -c contains-original.cc\", \"file\": \"contains-original.cc\"}]\nEOF\n\n# Run the tool (--disable-path-filter needed for test files)\nthird_party/llvm-build/Release+Asserts/bin/cef_cpp_rewriter \\\n  --disable-path-filter -p $TEST_DIR $TEST_DIR/contains-original.cc\n```\n\n### Running Tests\n\n```bash\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n### Debugging\n\n1. Add `dumpColor()` calls in `run()` to visualize matched AST nodes\n2. Return 1 from `main()` to see tool output (run_tool.py hides output on success)\n3. Dump AST: `clang++ -Xclang -ast-dump -std=c++20 file.cc`\n\n## Important Constraints\n\n1. **Symlink required**: The tool must be symlinked to `tools/clang/cef_cpp_rewriter`\n2. **Do not transform std::string**: Only associative containers have C++20 `.contains()`\n3. **Same container check**: Verify `find()` and `end()` are called on the same object\n4. **Skip macros**: Don't transform code inside macro expansions\n5. **CEF paths only**: Only transform files containing `/cef/` in their path\n\n## Compatibility Requirements\n\nCEF targets C++20. All transformations must work with these minimum toolchain versions:\n\n- GCC 10 (CEF minimum)\n- macOS 12.0 deployment target\n\nFeatures to AVOID (incompatible):\n\n- `std::string::contains()` - C++23, needs GCC 11+\n- `std::format` - needs GCC 13+ and macOS 13.3+\n- `using enum` - needs GCC 11+\n\n## Adding New Transformations\n\n### Quick Steps\n\n1. Add a command-line flag in `CefCppRewriter.cpp`:\n    ```cpp\n    static llvm::cl::opt<bool> EnableNewFeature(\"new-feature\",\n        llvm::cl::desc(\"Enable new feature transformation\"),\n        llvm::cl::init(true));\n    ```\n\n2. Create a new `MatchCallback` class for the transformation\n\n3. Add matcher to `match_finder` in `main()` guarded by the flag\n\n4. Add test files: `tests/newfeature-original.cc` and `tests/newfeature-expected.cc`\n\n5. Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n   (test_tool.py generates compile_commands.json automatically)\n\n### Full Implementation Checklist Template\n\nUse this checklist when implementing any new transformation:\n\n```markdown\n### Phase N: [Transformation Name]\n**Priority:** Nth | **Complexity:** Low/Medium/High | **Compat:** GCC X+\n\n[Brief description of the transformation]\n\n**Before/After Example:**\n```cpp\n// Before\n[old code pattern]\n\n// After\n[new code pattern]\n```\n\n**Checklist:**\n- [ ] Verify compatibility with GCC 10 and macOS 12.0 deployment target\n- [ ] Add `--flag-name` command-line flag (default: true/false)\n- [ ] Implement `TransformNameRewriter` class with:\n  - [ ] `run()` method that handles matched nodes\n  - [ ] Macro expansion filtering (`isMacroID()`, `isMacroBodyExpansion()`)\n  - [ ] System header filtering (`isInSystemHeader()`)\n  - [ ] Path filtering (skip non-CEF files unless `--disable-path-filter`)\n  - [ ] Deduplication via `processed_locations_` set\n- [ ] Create AST matcher(s) - test with `clang-query` first\n- [ ] Add matcher to `match_finder` in `main()` guarded by flag\n- [ ] Create test files: `transform-name-original.cc`, `transform-name-expected.cc`\n- [ ] Create negative test cases: `transform-name-negative-original.cc` (copy to `-expected.cc`)\n- [ ] Rebuild tool: `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n- [ ] Run tests: `python3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter`\n- [ ] Run on CEF code: `python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool --tool-args=\"--flag-name\" cef/libcef cef/libcef_dll cef/tests`\n- [ ] Review diffs and verify correctness\n- [ ] Build CEF to verify no compile errors\n- [ ] Run CEF tests to verify no regressions\n- [ ] Search for skipped instances (macros, edge cases) using grep\n- [ ] Manually transform skipped instances if appropriate\n- [ ] Update TRANSFORMS.md with transformation details\n- [ ] Update CLAUDE.md tool arguments table\n- [ ] Update README.md tool arguments table and transformations list\n```\n\n### Rewriter Class Template\n\n```cpp\nclass NewFeatureRewriter : public MatchFinder::MatchCallback {\n public:\n  explicit NewFeatureRewriter(OutputHelper* output) : output_helper_(*output) {}\n\n  void reset() { processed_locations_.clear(); }\n\n  void run(const MatchFinder::MatchResult& result) override {\n    const auto* matched_node = result.Nodes.getNodeAs<NodeType>(\"bindingName\");\n    if (!matched_node) return;\n\n    const SourceManager& sm = *result.SourceManager;\n    const LangOptions& opts = result.Context->getLangOpts();\n\n    // Skip macros\n    if (matched_node->getBeginLoc().isMacroID() ||\n        sm.isMacroBodyExpansion(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Skip system headers\n    if (sm.isInSystemHeader(matched_node->getBeginLoc())) {\n      return;\n    }\n\n    // Deduplicate\n    unsigned offset = sm.getFileOffset(matched_node->getBeginLoc());\n    if (processed_locations_.count(offset)) return;\n\n    // Path filter\n    if (!DisablePathFilter) {\n      StringRef filename = sm.getFilename(matched_node->getBeginLoc());\n      if (!filename.contains(\"/cef/\")) return;\n    }\n\n    processed_locations_.insert(offset);\n\n    // Generate replacement\n    std::string replacement = /* ... */;\n    CharSourceRange range = CharSourceRange::getTokenRange(\n        matched_node->getSourceRange());\n    output_helper_.Replace(range, replacement, sm, opts);\n  }\n\n private:\n  OutputHelper& output_helper_;\n  std::set<unsigned> processed_locations_;\n};\n```\n\n### Common Pitfalls\n\n1. **Iterator comparisons use overloaded operators**: Use `cxxOperatorCallExpr(hasOverloadedOperatorName(\"!=\"))` not `binaryOperator`\n2. **Integer literals need implicit cast handling**: Use `ignoringImpCasts(integerLiteral(...))`\n3. **Pointer access needs separate matching**: Include `hasType(pointsTo(...))` in an `anyOf()`\n4. **Token vs char ranges**: `getTokenRange()` includes full last token, `getCharRange()` is exact\n5. **Don't transform std::string methods**: Many string methods have same names but different semantics\n\n## Running the Tool on CEF Code\n\n```bash\n# Create build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool && cp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run all transformations (default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--contains=false --structured-bindings\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\nExample: `--tool-args=\"--only=iterator-loops\"` runs only the iterator-loops transformation.\n\n## Critical Reminders\n\n1. **Symlink required**: `test_tool.py` looks for tools in `tools/clang/`, so the symlink must exist\n2. **Test naming**: Files must be named `*-original.cc` and `*-expected.cc` (not `-test.cc`)\n3. **Do not transform `std::string::find()`**: Only associative containers have C++20 `.contains()`\n4. **Incremental builds**: Use `ninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter`\n5. **Do not re-run build.py**: It deletes everything and rebuilds from scratch (~30 min)\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory (from chromium/src)\n./cef/tools/clang/scripts/package_standalone.sh /path/to/cpp_rewriter\n\n# This creates a self-contained distribution:\n# /path/to/cpp_rewriter/\n# ├── bin/cpp_rewriter           # The tool binary (renamed from cef_cpp_rewriter)\n# ├── lib/clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper (auto-detects resource dir)\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\n**Key differences from CEF usage:**\n\n- Uses `--path-filter` for substring matching instead of default `/cef/` filter\n- Bundled clang headers allow tool to work without matching system clang\n- No `--generate-compdb` - requires pre-existing `compile_commands.json`\n- `CMAKE_EXPORT_COMPILE_COMMANDS` only works with Ninja/Makefiles generators (not Xcode/VS)\n\nSee `standalone/README.md` for complete standalone usage documentation.\n\n<!-- File: docs/architecture.md (Tokens: ~4964 | Category: project-spec) -->\nThis page provides an overview of the CEF architecture.\n\n**Contents**\n\n- [Overview](#overview)\n- [Dependencies](#dependencies)\n- [Versions](#versions)\n- [History](#history)\n- [Modern Architecture](#modern-architecture)\n- [Common API Usage](#common-api-usage)\n- [C Wrapper API](#c-wrapper-api)\n- [CEF1 (Discontinued)](#cef1-discontinued)\n  - [API Usage](#api-usage)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n- [CEF2 (Discontinued)](#cef2-discontinued)\n- [CEF3](#cef3)\n  - [API Usage](#api-usage)\n  - [Process Considerations](#process-considerations)\n  - [Threading Considerations](#threading-considerations)\n  - [Implementation Details](#implementation-details)\n    - [Alloy Runtime Classes](#alloy-runtime-classes)\n    - [Chrome Runtime Classes](#chrome-runtime-classes)\n\n---\n\n# Overview\n\nThe Chromium Embedded Framework (CEF) is an open source project founded by Marshall Greenblatt in 2008 to develop a Web browser control based on the [Google Chromium](http://www.chromium.org/Home) project. CEF currently supports a range of programming languages and operating systems and can be easily integrated into both new and existing applications. It was designed from the ground up with both performance and ease of use in mind. The base framework includes C and C++ programming interfaces exposed via native libraries that insulate the host application from Chromium and Blink implementation details. It provides close integration between the browser control and the host application, which can optionally control resource loading, navigation, context menus, printing, JavaScript bindings and more, while taking advantage of the same performance and HTML5 technologies available in the Google Chrome Web browser.\n\nSee the project [README.md](https://github.com/chromiumembedded/cef/blob/master/README.md) for additional introductory material.\n\n# Dependencies\n\nThe CEF project depends on a number of other projects maintained by third parties. The major projects that CEF depends on are:\n\n  * [Chromium](http://www.chromium.org/Home) - Provides general functionality like network stack, threading, message loop, logging and process control needed to create a fully functional Web browser. Implements \"platform\" code that allows Blink to communicate with V8 and Skia. Many Chromium design documents can be found at http://dev.chromium.org/developers.\n  * [Blink](https://www.chromium.org/blink) (formerly WebKit) - The rendering implementation used by Chromium. Provides DOM parsing, layout, event handling, rendering and HTML5 JavaScript APIs. Some HTML5 implementations are split between the Blink and Chromium code bases.\n  * [V8](https://developers.google.com/v8/) - JavaScript engine.\n  * [Skia](https://skia.org/) - 2D graphics library used for rendering non-accelerated content. More information on how Chromium integrates Skia is available [here](http://www.chromium.org/developers/design-documents/graphics-and-skia).\n  * [Angle](https://chromium.googlesource.com/angle/angle/+/master/README.md) - 3D graphics translation layer for Windows that converts GLES calls to DirectX. More information about accelerated compositing is available [here](http://dev.chromium.org/developers/design-documents/gpu-accelerated-compositing-in-chrome).\n\n# Versions\n\nThere have been three versions of CEF to date.\n\n  * CEF1 - Single process implementation using the Chromium WebKit API (now discontinued).\n  * CEF2 - Multi process implementation built on the Chromium browser (now discontinued).\n  * CEF3 - Multi process implementation using either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\").\n\nOnly the CEF3 version is currently developed and supported. See the \"History\" and \"Modern Architecture\" sections below for background and the [Branches And Building](branches_and_building.md) page for current development information.\n\n# History\n\nIn 2008, when the CEF project started, Chromium was a monolithic application built on top of Apple's [WebKit](https://webkit.org/) rendering engine. Google maintained an in-tree variant of WebKit (called the [Chromium WebKit API](https://www.youtube.com/watch?v=JFzC_Gx76E8)) that added additional functionality specific to Chromium. The first version of CEF (called CEF1) was implemented on top of this Chromium WebKit API and used the default single-process application model supported by WebKit1 at that time (for more details on CEF1 architecture see the \"CEF1\" section below).\n\nUse of the Chromium WebKit API came with some known limitations. For example, that API layer did not support the multi-process model that was the basis for most of Google Chrome's [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md). It also lacked many of the UI features that were becoming necessary to support new web platform features (like device selection dialogs, permissions management, etc). We therefore began a new effort, in 2010, to reimplement CEF (called CEF2) on top of the fully-featured but monolithic Chromium browser UI. The lack of internal API boundaries in the Chromium code at that time made it necessary for us to take an \"all or nothing\" approach. If we could create a CEF browser window based on the complete Chrome UI we would effectively gain access to all of Chrome's capabilities \"for free\" (for more details on CEF2 architecture see the \"CEF2\" section below).\n\nGoogle began acknowledging the validity of the embedded use case for Chromium in 2010 and started work on new internal API boundaries to make embedding easier. The [Chromium Content API](http://www.chromium.org/developers/content-module/content-api), which encapsulated the multi-process application model and provided stub implementations for most web platform features, reached a development stage in late 2011 where it was a viable option for Chromium embedders like CEF. It still didn't provide all of the features that we might like, but it was a \"supported\" API layer. We therefore abandoned the CEF2 effort in early 2012 and focused our efforts instead on the Content API as the more viable embedding option. The existing CEF1 API, which was strongly dependent on WebKit1 and the single-process model, could not be directly ported to the Content API. A new CEF API (called CEF3), with substantial breaking API changes and multi-process support, was released in early 2013 (for more details on CEF3 architecture see the \"Modern Architecture\" and \"CEF3\" sections below).\n\nAlso in 2013, Google decided to [fork the WebKit project](https://blog.chromium.org/2013/04/blink-rendering-engine-for-chromium.html). After renaming it to Blink they removed many of the API boundaries that had previously existed between Chromium and WebKit and effectively deleted the Chromium WebKit API. The multi-process architecture, which was optional in WebKit1, was now a requirement with Chromium/Blink. CEF1, which depended on the Chromium WebKit API, no longer had a viable future and CEF3 became the only path forward.\n\nFast forward another 7 years, to 2020, and the Chromium architecture has again changed substantially. A lot of effort has been spent to define clear architectural layers (sometimes called [components](https://www.chromium.org/developers/design-documents/cookbook/)) in the Chromium/Blink source code. New platforms and new embedders have entered the Chromium ecosystem. And yet, many features desired by CEF users remain stubbornly out of reach in the Chrome UI layer. With this new, more modern, version of Chromium, we decided it was time to revisit our goals from CEF2 and create a new CEF version based on the Chrome UI layer (now called the \"Chrome runtime\" in CEF3). Continue to the \"Modern Architecture\" section for details.\n\n# Modern Architecture\n\nThe modern Chromium code base is composed of architectural layers, with the primary application layers being \"content\" (for the [Content API](http://www.chromium.org/developers/content-module/content-api)) and \"chrome\" (for the Chrome UI layer). The \"content\" layer includes [WebContents](https://source.chromium.org/chromium/chromium/src/+/master:content/public/browser/web_contents.h) as the primary browser object and provides implementations for most of the generic web platform and application/process management functionality. The \"chrome\" layer includes [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) as the primary browser object and provides implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc.\n\nFor historical reasons (outlined above), CEF browser windows have been based on the \"content\" layer WebContents object since the introduction of CEF3 in 2013. Adding support for additional \"chrome\" layer features in that architecture was a serious effort because it involved careful understanding and cherry-picking of the related functionality from \"chrome\" code into the CEF code base. Over time we have added dependencies on the \"chrome\" layer targets to support some features in CEF (such and extensions, PDF viewer and print preview) and to avoid code duplication. As a result, CEF3 binaries in modern times already contained most/all of the code that would be required to launch a stand-alone \"chrome\" Browser window, but simply lacked the mechanism to do so.\n\nIn 2020 we launched a [new effort](https://github.com/chromiumembedded/cef/issues/2969) to implement the CEF3 API on top of a fully-featured \"chrome\" Browser window. To be usable in existing CEF3 client applications the \"chrome\" window needed to support a large subset of CEF3's existing callbacks/intercepts (e.g. loading progress, network requests, etc.), and be inserted into the existing [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) structure. At the same time, it was necessary to substantially refactor the internal CEF (libcef) code to extract functionality that was common to both the old WebContents-based approach and the new Browser-based approach. As part of this refactoring we renamed the existing \"content\" layer implementation to the \"Alloy runtime\" (where Alloy = Chrome + other stuff) and named the new \"chrome\" layer implementation as the \"Chrome runtime\". Proceed to the \"CEF3\" section below for additional feature and implementation details.\n\n# Common API Usage\n\nAll versions of CEF expose a simple, easy-to-use API designed to insulate users from the underlying Chromium and Blink code complexity. Common usage is as follows:\n\n1. Initialize CEF by calling CefInitialize().\n\n2. Perform work on the UI message loop by calling CefRunMessageLoop() or CefDoMessageLoopWork().\n\n3. Create a browser window by calling CreateBrowser() or CreateBrowserSync() and passing in a CefClient instance.\n\n4. Shut down CEF by calling CefShutdown() before the application exits.\n\n# C Wrapper API\n\nThe libcef shared library exports a C API that isolates the user from the CEF runtime and code base. The libcef\\_dll\\_wrapper project, which is distributed in source code form as part of the binary release, wraps this exported C API in a C++ API that is then linked into the client application. The code for this C/C++ API translation layer is automatically generated by the [translator](https://github.com/chromiumembedded/cef/blob/master/tools/translator.README.txt) tool. Direct usage of the C API is described on the [Using The CAPI](using_the_capi.md) page.\n\n# CEF1 (Discontinued)\n\nCEF1 was the initial version of CEF first released in 2008. It was discontinued in 2013 when Google forked the WebKit project and subsequently deleted the Chromium WebKit API. See the \"History\" section above for additional details.\n\nThe single process architecture used by CEF1 integrates Chromium and WebKit directly into the client application. Advantages to the single process architecture included reduced memory usage and closer integration with the client application. For example, having the renderer running in the same process allowed JavaScript bindings to synchronously communicate between client code and renderer code. Disadvantages included [reduced performance](https://github.com/chromiumembedded/cef/issues/304) with certain types of accelerated content, [crashes](https://github.com/chromiumembedded/cef/issues/242) due to plugins like Flash running in the same process, and lack of support for application [security and stability features](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md) that required a multi-process architecture.\n\n## API Usage\n\nBelow is an overview of the main CEF1 interfaces and their uses. Since CEF1 is discontinued we no longer provide detailed usage information.\n\n  * [CefApp](http://magpcss.org/ceforum/apidocs/projects/(default)/CefApp.html) - This interface is passed to CefInitialize() and allows the application to customize global functionality like resource loading and proxy handling.\n  * [CefClient](http://magpcss.org/ceforum/apidocs/projects/(default)/CefClient.html) - This interface is passed to CefCreateBrowser() or CefCreateBrowserSync() and acts as the connection between an individual CEF browser instance and the client application. Additional interfaces for request handling, display handling, etc. are exposed via this interface.\n  * [CefBrowser](http://magpcss.org/ceforum/apidocs/projects/(default)/CefBrowser.html) - Exposes capabilities provided by the browser. This includes back/forward navigation, source retrieval, request loading, etc. A single CefBrowser may have one or more child [CefFrame](http://magpcss.org/ceforum/apidocs/projects/(default)/CefFrame.html) objects.\n\n## Threading Considerations\n\nCEF1 includes UI, IO and FILE threads. The UI thread creates browser windows and is used for all interaction with WebKit and V8. The IO thread is used for handling schema and network requests. The FILE thread is used for the application cache and other miscellaneous activities.\n\nWhen using CEF1 you should keep the following threading considerations in mind:\n\n  * Do not perform blocking operations on the UI thread. This can lead to serious performance issues.\n  * The UI thread will be the same as the main application thread if CefInitialize() is called with a CefSettings.multi\\_threaded\\_message\\_loop value of false.\n  * All WebKit and V8 interation must take place on the UI thread. Consequently, some CEF API functions can only be called on the UI thread. Functions that have this limitation will be documented accordingly in the associated CEF header file.\n  * The [CefPostTask](http://magpcss.org/ceforum/apidocs/projects/(default)/(_globals).html#CefPostTask(CefThreadId,CefRefPtr<CefTask>)) method can be used to post tasks asnychronously between the various threads.\n\n## Implementation Details\n\nCEF1 has the following major implementation classes:\n\n  * CefContext - Represents the global CEF context. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * CefProcess - Used by CefContext to create and manage the CEF threads.\n  * BrowserWebKitInit - Manages the global WebKit environment as exposed by the Chromium WebKit API.\n  * WebViewHost - Provides the native window \"wrapper\" implementation for a WebView. This class extends WebWidgetHost which provides functionality shared in common with popup widgets (like select menus) on some platforms.\n  * CefBrowserImpl - Implements the CefBrowser interface, creates the WebViewHost and provides the glue code for a single browser instance.\n  * BrowserWebViewDelegate - Implements the WebKit interfaces that provide communication between CefBrowserImpl and the underlying WebView.\n\n# CEF2 (Discontinued)\n\nCEF2 was an effort to reimplement the CEF1 API on top of the Chrome browser UI as it existed in 2010. CEF2 was discontinued when Chromium announced support for the Content API. Information about CEF2 can be found in the \"History\" section above and [here](http://magpcss.org/ceforum/viewtopic.php?f=10&t=122) on the CEF Forum.\n\n# CEF3\n\nCEF3 has been the recommended and supported version of CEF since January 2013. It uses the same multi process architecture as the Chromium Web browser via either the [Chromium Content API](http://www.chromium.org/developers/content-module/content-api) (called the \"Alloy runtime\") or the complete Chrome UI (called the \"Chrome runtime\"). This architecture provides a number of advantages over the single process architecture used by CEF1:\n\n  * Support for multi-process run mode (with related [stability and security advantages](https://chromium.googlesource.com/playground/chromium-org-site/+/refs/heads/main/developers/design-documents/multi-process-architecture/index.md)).\n  * More code sharing with the Chromium browser.\n  * Improved performance and less breakage due to use of the \"supported\" code path.\n  * Faster access to new features.\n\nIn most cases CEF3 will have the same performance and stability characteristics as the Chromium Web browser. Both the Alloy runtime and the Chrome runtime support modern web platform features and provide the safety/security expected from an up-to-date Chromium-based browser. The Chrome runtime, which was introduced in 2020, adds implementations for many advanced features (including datalist/autofill, extensions, gamepad, webhid, webmidi, etc.), along with standard Chrome UI toolbars and dialogs for device selection, user permissions, settings, etc. At the time of writing, the Chrome runtime requires use of the [Views framework](https://www.chromium.org/developers/design-documents/chromeviews/) in CEF client applications and does not support off-screen rendering. A current list of open issues specific to the Chrome runtime can be found [here](https://github.com/chromiumembedded/cef/issues?q=is%3Aissue+is%3Aopen+label%3Achrome).\n\nStarting with the M125 release (mid-2024) the Alloy runtime has been [split](https://github.com/chromiumembedded/cef/issues/3681) into separate style and bootstrap components. Both Chrome style and Alloy style browsers/windows can now be created while using the Chrome bootstrap. The Alloy bootstrap has been [removed](https://github.com/chromiumembedded/cef/issues/3685) starting with the M128 release.\n\n## API Usage\n\nSee the [General Usage](general_usage.md) page for detailed API usage instructions.\n\n## Process Considerations\n\nSee the [Processes](general_usage.md#processes) section of the [General Usage](general_usage.md) page for details.\n\n## Threading Considerations\n\nSee the [Threads](general_usage.md#threads) section of the [General Usage](general_usage.md) page for details.\n\n## Implementation Details\n\nFor an implementation overview see the \"Modern Architecture\" section above. \n\nShared CEF library/runtime classes use the Cef prefix. Classes that implement the Alloy or Chrome runtime use the Alloy or Chrome prefixes respectively. Classes that extend an existing Chrome-prefixed class add the Cef or Alloy suffix, thereby following the existing naming pattern of Chrome-derived classes.\n\n### Alloy Runtime Classes\n\nAlloy runtime bootstrap was [removed](https://github.com/chromiumembedded/cef/issues/3685) in M128 (mid-2024) and Alloy runtime style is now supported using the Chrome runtime bootstrap. Alloy runtime style is based on the \"content\" layer and has the following major implementation classes:\n\n  * [AlloyBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/alloy/alloy_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n\n### Chrome Runtime Classes\n\nChrome runtime bootstrap and style is based on the \"chrome\" layer and has the following major implementation classes:\n\n  * [ChromeMainDelegateCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_main_delegate_cef.h) - Implements the common process bootstrap logic.\n  * [ChromeContentClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/common/chrome/chrome_content_client_cef.h) - Implements the Content API callbacks that are common to all processes.\n  * [CefContext](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/context.h) - Represents the global CEF context in the browser process. A single CefContext object is created by CefInitialize() and destroyed by CefShutdown().\n  * [ChromeBrowserMainExtraPartsCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_main_extra_parts_cef.h) - Implements the browser process bootstrap logic.\n  * [ChromeContentBrowserClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_content_browser_client_cef.h) - Implements the Content API callbacks for the browser process.\n  * [ChromeBrowserHostImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_host_impl.h) - Implements the CefBrowser and CefBrowserHost interfaces in the browser process. Provides the glue code and implements interfaces for communicating with the RenderViewHost.\n  * [ChromeContentRendererClientCef](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/chrome/chrome_content_renderer_client_cef.h) - Implements the Content API callbacks for the render process.\n  * [CefBrowserImpl](https://github.com/chromiumembedded/cef/blob/master/libcef/renderer/browser_impl.h) - Implements the CefBrowser interface in the render process. Provides the glue code and implements interfaces for communicating with the RenderView.\n  * [ChromeBrowserDelegate](https://github.com/chromiumembedded/cef/blob/master/libcef/browser/chrome/chrome_browser_delegate.h) - Interface injected into Chrome's [Browser](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser.h) object (via [patch files](https://github.com/chromiumembedded/cef/blob/master/patch/README.txt)) to support callbacks into CEF code.\n  * [ChromeBrowserFrame](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h) - Widget for a Views-hosted Chrome browser.\n\nAn overview of the Chrome Browser object model is also available [here](https://github.com/chromiumembedded/cef/blob/ecdfd467f84da9bb6ef57eb4fcb2778fdef5e07a/libcef/browser/chrome/views/chrome_browser_frame.h).\n\n<!-- File: tools/cefbuilds/README.md (Tokens: ~1266 | Category: plugin-manifest) -->\n# CEF Builds JSON Tools\n\nTools for generating and maintaining the JSON index files used by the\n[CEF Builds](https://cef-builds.spotifycdn.com/index.html) CDN and the CEF\ninstaller.\n\n## Files\n\n### Core libraries\n\n- **`cef_json_builder.py`** — Builds and maintains the master `index.json` file\n  that contains the full catalog of CEF binary distributions across all\n  platforms, versions, and channels. Handles file metadata (name, size, sha1,\n  last_modified), Chromium version mapping, and sandbox compatibility hashes.\n\n- **`cef_installer_builder.py`** — Generates installer-optimized CDN query files\n  from a populated `cef_json_builder` instance. Produces lightweight JSON files\n  designed for efficient HTTP HEAD timestamp checks by the CEF installer.\n\n### Data files\n\n- **`revoked.json`** — Manually maintained list of revoked CEF versions. Revoked\n  versions are excluded from all installer-generated JSON output. The installer\n  also fetches this file from the CDN and refuses to install any listed version.\n\n### Examples and tests\n\n- **`cef_json_builder_example.py`** — Example script demonstrating\n  `cef_json_builder` usage. Creates and updates a local `index.json` with fake\n  file data.\n\n- **`cef_json_builder_test.py`** — Unit tests for `cef_json_builder`.\n\n- **`cef_installer_builder_test.py`** — Unit tests for `cef_installer_builder`.\n\n## CDN file formats\n\n### Master index\n\n- **`index.json`** — Full data index of all CEF binary distributions. Generated\n  by `cef_json_builder`. Keyed by platform, with version records sorted\n  newest-first by file last_modified timestamp.\n\n### Installer query files\n\nGenerated by `cef_installer_builder` from the master index:\n\n- **`stable.txt`** — Current stable milestone number (e.g., `137`).\n\n- **`{milestone}.json`** (e.g., `137.json`) — Newest build per platform for a\n  given milestone. Used by the installer to check if an update is available.\n\n- **`{milestone}_{platform}.json`** (e.g., `137_windows64.json`) — All builds\n  for a milestone+platform combination, sorted newest-first.\n\n- **`{abi_hash}_{platform}.json`** (e.g., `abc123def4567890_windows64.json`) —\n  All builds compatible with a given ABI hash and platform across all milestones,\n  sorted newest-first. Windows platforms only (tied to `chrome_elf.dll` /\n  Chromium sandbox ABI).\n\n## Concepts\n\n### Platforms\n\nSupported platforms: `linux32`, `linux64`, `linuxarm`, `linuxarm64`,\n`macosarm64`, `macosx64`, `windows32`, `windows64`, `windowsarm64`.\n\n### Distribution types\n\nEach version may have files of these types: `standard`, `minimal`, `client`,\n`tools`, `release_symbols`, `debug_symbols`, `signed`.\n\nThe `signed` type contains code-signed archives with catalog files, used by the\ninstaller for verified installation.\n\n### Channels\n\nVersions belong to either the `stable` or `beta` channel.\n\n### Version formats\n\n- **New-style**: `137.3.5+g62d140e+chromium-137.0.7204.6`\n  - Short version: `137.3.5` (everything before the first `+`)\n  - Milestone: `137` (major version number)\n- **Old-style**: `3.2704.1414.g185cd6c` (predates the installer format)\n\n### ABI hash (`sandbox_compat`)\n\nA 16-character hex string identifying the Windows sandbox ABI compatibility\nlevel. Derived from `cef_api_versions.json` on GitHub. Versions sharing the same\nABI hash can use the same `chrome_elf.dll` and are interchangeable from the\nsandbox's perspective.\n\n### Revocation\n\nThe `revoked.json` file lists versions that must not be installed. When passed\nto `cef_installer_builder`, revoked versions are automatically excluded from\nall generated output. The installer also fetches this file from the CDN at\nruntime and refuses to install any listed version.\n\nEntries can revoke a single version or a range of versions:\n\n```json\n{\n  \"revoked_versions\": [\n    {\n      \"version\": \"137.1.0\",\n      \"reason\": \"CVE-2024-XXXXX: critical sandbox escape\",\n      \"revoked_at\": \"2024-01-15T00:00:00Z\"\n    },\n    {\n      \"version_min\": \"138.0.0\",\n      \"version_max\": \"138.2.99\",\n      \"reason\": \"CVE-2024-YYYYY: affects all 138.0–138.2 builds\",\n      \"revoked_at\": \"2024-02-01T00:00:00Z\"\n    }\n  ]\n}\n```\n\n**Single version** (point revocation):\n- `version` — Short version string (e.g., `137.1.0`).\n\n**Version range** (inclusive):\n- `version_min` — Inclusive lower bound (e.g., `138.0.0`).\n- `version_max` — Inclusive upper bound (e.g., `138.2.99`).\n\n**Common fields:**\n- `reason` — Human-readable explanation (CVE ID, bug reference, etc.).\n- `revoked_at` — ISO 8601 timestamp of when the revocation was added.\n\nA single-version entry using `version` is equivalent to setting both\n`version_min` and `version_max` to the same value. If both `version` and\n`version_min`/`version_max` are present, the range fields take precedence.\n\n## Running tests\n\n```bash\ncd cef/tools/cefbuilds\npython3 -m unittest cef_json_builder_test -v\npython3 -m unittest cef_installer_builder_test -v\n```\n\n<!-- File: tools/clang/README.md (Tokens: ~2181 | Category: plugin-manifest) -->\n# CEF Clang Tools\n\nThis directory contains clang-based tools for CEF code modernization and refactoring.\n\n## Tools\n\n### cef_cpp_rewriter\n\nA clang AST-based rewriter tool for automating C++20 modernization of CEF code.\n\n**Supported transformations:**\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for complete documentation of all transformations, command-line flags, and examples.\n\n## Prerequisites\n\n- Chromium checkout with CEF\n- **Python 3.10+** (Chromium's build scripts require it)\n- ~30 minutes for initial clang bootstrap\n\n**Note:** CEF is a separate git repository within chromium/src. Chromium's clang\ntool scripts (`run_tool.py`, `test_tool.py`, `apply_edits.py`) use git commands\nthat don't work across repository boundaries. This directory provides CEF-specific\nreplacements: `run_tool.py`, `test_tool.py`, and `apply_edits.py`.\n\n### Python Version\n\nmacOS ships with Python 3.9 which is too old. Install Python 3.12 via Homebrew:\n\n```bash\nbrew install python@3.12\nln -s /opt/homebrew/opt/python@3.12/bin/python3.12 /opt/homebrew/opt/python@3.12/bin/python3\nexport PATH=\"/opt/homebrew/opt/python@3.12/bin:$PATH\"\npython3 --version  # Should show 3.12.x\n```\n\nAdd the export line to `~/.zshrc` to make it permanent.\n\n## Quick Start\n\n### Initial Setup (one-time, ~30 minutes)\n\n```bash\n# From chromium/src directory\n./cef/tools/clang/scripts/build_clang_rewriter.sh\n```\n\nThis will:\n\n1. Create a symlink from `tools/clang/cef_cpp_rewriter` to the CEF tool\n2. Bootstrap clang with the tool (~30 minutes)\n\n**Warning:** The clang bootstrap updates `third_party/llvm-build/`, which will\ninvalidate all existing Chromium/CEF build directories and trigger a full\nrebuild the next time you build. Plan accordingly.\n\n### Running the Tool\n\n```bash\n# Create a build directory for clang tooling\n# Start with the contents of your CEF build args (e.g., out/Debug_GN_arm64/args.gn)\n# and make the following modifications:\n#   - Add: enable_precompiled_headers=false (required for clang tools)\n#   - Add: dcheck_always_on=true (to cover DCHECK code paths)\n#   - Change: is_debug=false (faster builds)\n#   - Change: is_component_build=true (faster linking)\nmkdir -p out/ClangTool\ncp out/Debug_GN_arm64/args.gn out/ClangTool/args.gn\n# Edit out/ClangTool/args.gn to add/modify the above settings, then:\ngn gen out/ClangTool\n\n# Build only CEF-related gen targets (~9k vs ~39k for all of Chromium)\n./cef/tools/clang/scripts/build_gen_targets.sh out/ClangTool\n\n# Run the tool on CEF code (all transformations enabled by default)\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Run only specific transformations using --tool-args\npython3 cef/tools/clang/scripts/run_tool.py \\\n  -p out/ClangTool \\\n  --tool-args=\"--structured-bindings --contains=false\" \\\n  cef/libcef cef/libcef_dll cef/tests > /tmp/edits-raw.txt\n\n# Or run on all CEF files (omit path arguments)\n# python3 cef/tools/clang/scripts/run_tool.py -p out/ClangTool\n\n# Process and apply the edits\n# Note: --base-dir must match the -p argument since paths are relative to build dir\ncat /tmp/edits-raw.txt \\\n  | python3 cef/tools/clang/scripts/process_edits.py \\\n  | python3 cef/tools/clang/scripts/apply_edits.py --base-dir out/ClangTool\n```\n\n### Tool Arguments\n\nThe `--tool-args` option passes arguments directly to `cef_cpp_rewriter`.\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags.\n\n**Examples:**\n```bash\n# Run only iterator-loops transformation\n--tool-args=\"--only=iterator-loops\"\n\n# Run only contains and structured-bindings\n--tool-args=\"--only=contains,structured-bindings\"\n\n# Disable specific transformation (all others still run)\n--tool-args=\"--contains=false\"\n```\n\n### Incremental Rebuilds\n\nAfter modifying `CefCppRewriter.cpp`, rebuild quickly with:\n\n```bash\nninja -C third_party/llvm-build/Release+Asserts cef_cpp_rewriter\n```\n\n**Do not re-run `build_clang_rewriter.sh`** - it rebuilds everything from scratch.\n\n## Testing\n\n```bash\n# Run tool tests\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter\n\n# With verbose output\npython3 cef/tools/clang/scripts/test_tool.py cef_cpp_rewriter --verbose\n```\n\n## Compatibility\n\nCEF targets C++20. See [TRANSFORMS.md](TRANSFORMS.md) for minimum toolchain versions.\n\n## Standalone Distribution\n\nThe tool can be packaged for use on any C++ project (not just CEF):\n\n```bash\n# Package to a target directory\n./cef/tools/clang/scripts/package_standalone.sh /path/to/target\n\n# This creates:\n# /path/to/target/\n# ├── bin/cpp_rewriter           # The tool binary\n# ├── lib/clang/<version>/       # Bundled clang headers\n# ├── scripts/\n# │   ├── run_rewriter.py        # Standalone wrapper\n# │   ├── apply_edits.py\n# │   └── process_edits.py\n# └── README.md\n```\n\nThe standalone distribution is self-contained and includes bundled clang headers\nso it works without requiring a matching system clang installation.\n\n**Usage on any CMake project:**\n```bash\ncd my-project\n\n# Generate compile_commands.json (requires Ninja or Makefiles generator)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Run the rewriter\n/path/to/target/scripts/run_rewriter.py -p build src/ \\\n  | /path/to/target/scripts/apply_edits.py --base-dir build\n```\n\nSee `standalone/README.md` for complete standalone usage documentation.\n\n## Directory Structure\n\n```\ncef/tools/clang/\n├── cef_cpp_rewriter/\n│   ├── CMakeLists.txt\n│   ├── CefCppRewriter.cpp\n│   ├── OutputHelper.h\n│   ├── OutputHelper.cpp\n│   └── tests/\n│       ├── contains-original.cc\n│       ├── contains-expected.cc\n│       ├── contains-negative-original.cc\n│       ├── contains-negative-expected.cc\n│       ├── disallow-copy-original.cc\n│       ├── disallow-copy-expected.cc\n│       ├── disallow-copy-negative-original.cc\n│       ├── disallow-copy-negative-expected.cc\n│       ├── structured-bindings-original.cc\n│       ├── structured-bindings-expected.cc\n│       ├── structured-bindings-negative-original.cc\n│       ├── structured-bindings-negative-expected.cc\n│       ├── iterator-loops-original.cc\n│       ├── iterator-loops-expected.cc\n│       ├── iterator-loops-negative-original.cc\n│       └── iterator-loops-negative-expected.cc\n├── scripts/\n│   ├── apply_edits.py            # Applies edits (no git dependency)\n│   ├── build_gen_targets.sh      # Build CEF-related gen targets only\n│   ├── build_clang_rewriter.sh   # Bootstrap clang with the tool\n│   ├── package_standalone.sh     # Package for standalone use\n│   ├── process_edits.py          # Adds markers, deduplicates edits\n│   ├── run_tool.py               # Run tool on CEF files\n│   └── test_tool.py              # CEF-specific test harness\n├── standalone/\n│   ├── README.md                 # Standalone usage documentation\n│   └── run_rewriter.py           # Standalone wrapper script\n├── CLAUDE.md\n├── README.md\n└── TRANSFORMS.md                 # Transformation documentation\n```\n\n## Maintenance\n\nThis tool is not regularly tested. It may need updates when:\n\n| Trigger | Likely Fix |\n|---------|------------|\n| Chromium updates `tools/clang/` infrastructure | Update `CMakeLists.txt`, check `build.py` flags |\n| LLVM/Clang API changes | Update AST matcher syntax, check deprecations in Clang doxygen |\n| CEF adopts C++23 | Add `flat_map`/`flat_set` container types to matcher |\n| Build fails after Chromium update | Compare with current `tools/clang/ast_rewriter/` example |\n\n### Diagnosing Build Failures\n\nIf the tool fails to build after a Chromium update:\n\n1. Check if `ast_rewriter` still exists and builds:\n    ```bash\n    python3 tools/clang/scripts/build.py --bootstrap --extra-tools ast_rewriter\n    ```\n\n2. Compare CMakeLists.txt with the current ast_rewriter version:\n    ```bash\n    diff cef/tools/clang/cef_cpp_rewriter/CMakeLists.txt tools/clang/ast_rewriter/CMakeLists.txt\n    ```\n\n3. Check for API changes in Clang's AST matchers (review Clang release notes)\n\n### Cleanup\n\nAfter running the tool, you may want to remove the symlink:\n\n```bash\nrm tools/clang/cef_cpp_rewriter  # Removes symlink only, not CEF source\n```\n\n## Resources\n\n- Chromium clang tool documentation: `docs/clang_tool_refactoring.md`\n- Chromium example: `tools/clang/ast_rewriter/`\n- [AST Matcher Reference](https://clang.llvm.org/docs/LibASTMatchersReference.html)\n- [LibTooling Tutorial](https://clang.llvm.org/docs/LibASTMatchersTutorial.html)\n\n<!-- File: tools/clang/standalone/README.md (Tokens: ~1130 | Category: plugin-manifest) -->\n# C++ Rewriter Tool\n\nA clang-based AST rewriter for C++20 modernization. This tool performs\ntype-aware code transformations that cannot be done with simple regex,\nsuch as replacing `map.find(x) != map.end()` with `map.contains(x)`.\n\n## Distribution Contents\n\nThis is a self-contained distribution that includes everything needed to run:\n\n```\ncpp_rewriter/\n├── bin/\n│   └── cpp_rewriter           # The clang-based rewriter tool\n├── lib/\n│   └── clang/<version>/       # Bundled clang headers (stdarg.h, etc.)\n│       └── include/\n├── scripts/\n│   ├── run_rewriter.py        # Main wrapper script\n│   ├── apply_edits.py         # Applies generated edits to files\n│   └── process_edits.py       # Deduplicates and formats edits\n└── README.md\n```\n\nThe bundled `lib/clang/` headers are automatically detected and used by the\nwrapper script, so the tool works without requiring a matching system clang.\n\n## Prerequisites\n\n- A C++ project with a `compile_commands.json` file\n- Python 3.6+\n\n## Generating compile_commands.json\n\nThe tool requires a compilation database to understand your project's\nbuild configuration. Here's how to generate one for common build systems:\n\n### CMake\n\n**Important:** `CMAKE_EXPORT_COMPILE_COMMANDS` only works with **Makefile**\nand **Ninja** generators. It does NOT work with Xcode or Visual Studio generators.\n\n```bash\n# Using Ninja (recommended)\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# Using Unix Makefiles\ncmake -G \"Unix Makefiles\" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build\n\n# compile_commands.json is now in build/\n```\n\nIf you normally use Xcode/Visual Studio, create a separate build directory\njust for tooling:\n\n```bash\n# Keep your Xcode build, add a parallel Ninja build for tools\ncmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build-tools\n# Use build-tools/compile_commands.json with the rewriter\n```\n\n### Meson\n\n```bash\nmeson setup build\n# compile_commands.json is automatically generated in build/\n```\n\n### Bear (for Make-based projects)\n\n```bash\n# Install Bear: https://github.com/rizsotto/Bear\nbear -- make\n# compile_commands.json is generated in current directory\n```\n\n### Ninja\n\n```bash\nninja -C build -t compdb > build/compile_commands.json\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Run on all files in compile_commands.json\n./scripts/run_rewriter.py -p /path/to/build | ./scripts/apply_edits.py --base-dir /path/to/build\n\n# Run on specific source directories only\n./scripts/run_rewriter.py -p build src/ include/ | ./scripts/apply_edits.py --base-dir build\n```\n\n### Filter by Path Pattern\n\nUse `--path-filter` with a substring to process only matching files:\n\n```bash\n# Only process files containing \"src/core/\" in their path\n./scripts/run_rewriter.py -p build --path-filter \"src/core/\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Disable Specific Transformations\n\n```bash\n# Disable structured bindings transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--structured-bindings=false\" | ./scripts/apply_edits.py --base-dir build\n\n# Run only the .contains() transformation\n./scripts/run_rewriter.py -p build --tool-args=\"--only=contains\" | ./scripts/apply_edits.py --base-dir build\n```\n\n### Verbose Output\n\n```bash\n# Show progress\n./scripts/run_rewriter.py -p build -v src/ 2>&1 | tee /tmp/edits.txt\n./scripts/apply_edits.py --base-dir build < /tmp/edits.txt\n```\n\n## Available Transformations\n\n- `.contains()` for associative containers\n- Structured bindings for range-for loops\n- Iterator loops to range-for\n- DISALLOW_COPY_AND_ASSIGN replacement\n\nAll transformations are enabled by default. Use `--flag=false` to disable specific ones,\nor `--only=<list>` to run only specific transformations.\n\nSee [TRANSFORMS.md](TRANSFORMS.md) for the complete list of command-line flags,\nbefore/after examples, supported containers, and edge cases.\n\n## Troubleshooting\n\n### \"compile_commands.json not found\"\n\nMake sure you've generated the compilation database. See the\n\"Generating compile_commands.json\" section above.\n\n### \"No files found matching...\"\n\n- Check that the path filter matches your file paths\n- Use `-v` for verbose output to see which files are being processed\n- Try running without a path filter first\n\n### Transformations not applying\n\n- The tool only transforms code, not macro expansions\n- Some patterns may not match due to unusual formatting\n- Use `-v` to see error messages from the tool\n\n## Compatibility\n\nThe transformed code uses C++20 features. See [TRANSFORMS.md](TRANSFORMS.md) for\nminimum compiler requirements.\n\n## Building from Source\n\nThis tool is built as part of the CEF (Chromium Embedded Framework) project.\nSee the CEF repository for build instructions.\n\n<!-- File: tools/claude/README.md (Tokens: ~2782 | Category: plugin-manifest) -->\n# Tools and Detailed Instructions for CEF Development\n\nThis directory contains tools and detailed instructions for using coding\nagents to assist with CEF (Chromium Embedded Framework) development. Use these\nguides with models that benefit from explicit workflows, examples, and\nverification steps, including Claude Opus 4.x and GPT Terra.\n\nThe guides were originally written for Claude Code and retain their `CLAUDE_*`\nfilenames. Other coding agents can use them directly; adapt any Claude-specific\nsetup or file attachment syntax to your agent. For GPT Sol or other frontier\nmodels that work well with concise instructions, see the\n[GPT guides](../gpt/README.md) for concise patch and build instructions and\nexample prompts. For other tasks, newer frontier models can often discover the\nrelevant details themselves, using the detailed instruction files here as\nreference material when needed.\n\n***\n[TOC]\n***\n\n## Quick Navigation\n\n**Are you updating CEF to a new Chromium version?**\n\n→ See [CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md) for the complete workflow:\n\n- Fixing patches that fail to apply\n- Fixing build errors from API changes\n- Using analyzer scripts and verification tools\n\n**Are you developing a CEF application using a binary distribution?**\n\n→ See [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md) for implementing features:\n\n- Adding custom URL schemes\n- JavaScript-to-C++ communication\n- Network request interception\n- Popup window customization\n\n**Are you writing or debugging CEF unit tests?**\n\n→ See [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md) for working with ceftests:\n\n- Running existing unit tests\n- Creating new tests for CEF features\n- Debugging test failures and flakiness\n- Using TestHandler, RoutingTestHandler, and TestServer\n\n**Are you developing libcef internals (CEF implementation code)?**\n\n→ See [CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md) for libcef development patterns:\n\n- Adding new CEF APIs with proper versioning\n- Implementing WebContentsDelegate callbacks\n- Working with Chrome and Alloy browser styles\n- Finding and fixing NOTIMPLEMENTED() stubs\n\n**Are you syncing CEF base headers with Chromium?**\n\n→ See [CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md) for synchronizing `cef/include/base/` headers:\n\n- CEF-specific modifications (namespaces, includes, platform macros)\n- Files to sync vs files to preserve\n- Handling C++23 reverts\n- Step-by-step sync process\n\n**Are you cherry-picking commits from upstream CEF?**\n\n→ See [CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md) for cherry-picking commits that include patch files:\n\n- Extracting and applying source file changes from patches\n- Resaving patches with correct index hashes\n- Handling multiple patch files per commit\n- Recovery when things go wrong\n\n**Are you applying a Chromium commit to CEF as a patch?**\n\n→ See [CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md) for creating or updating CEF patches from Chromium commits:\n\n- Creating new patch files and adding to patch.cfg\n- Adding changes to existing patch files\n- Handling version differences between Chromium versions\n- Verifying patches can be reverted and reapplied\n\n**Are you improving unit test coverage?**\n\n→ See [CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md) for running and analyzing code coverage:\n\n- Human prerequisites for setting up coverage builds\n- Building and running tests with coverage instrumentation\n- Analyzing coverage reports to identify gaps\n- Workflow for improving function and line coverage\n\n## Files in This Directory\n\n### Documentation\n\n- **[CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md)** - Complete guide for updating CEF to new Chromium versions\n- **[CLAUDE.md.in](CLAUDE.md.in)** - Template for root CLAUDE.md (copied by setup_claude.py)\n- **[CLAUDE_BASE_SYNC_INSTRUCTIONS.md](CLAUDE_BASE_SYNC_INSTRUCTIONS.md)** - Instructions for syncing CEF base headers with Chromium\n- **[CLAUDE_BUILD_INSTRUCTIONS.md](CLAUDE_BUILD_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing build errors\n- **[CLAUDE_CHERRY_PICK_INSTRUCTIONS.md](CLAUDE_CHERRY_PICK_INSTRUCTIONS.md)** - Instructions for cherry-picking commits from upstream CEF that include patch files\n- **[CLAUDE_CLIENT_INSTRUCTIONS.md](CLAUDE_CLIENT_INSTRUCTIONS.md)** - Detailed instructions for Claude agents implementing features in CEF applications\n- **[CLAUDE_COVERAGE_INSTRUCTIONS.md](CLAUDE_COVERAGE_INSTRUCTIONS.md)** - Instructions for running and analyzing code coverage\n- **[CLAUDE_LIBCEF_INSTRUCTIONS.md](CLAUDE_LIBCEF_INSTRUCTIONS.md)** - Detailed instructions for Claude agents developing libcef internals (API versioning, WebContentsDelegate)\n- **[CLAUDE_PATCH_INSTRUCTIONS.md](CLAUDE_PATCH_INSTRUCTIONS.md)** - Detailed instructions for Claude agents fixing patch failures\n- **[CLAUDE_SRC_PATCH_INSTRUCTIONS.md](CLAUDE_SRC_PATCH_INSTRUCTIONS.md)** - Instructions for applying Chromium commits to CEF as new or existing patches\n- **[CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md)** - Detailed instructions for Claude agents creating and running CEF unit tests\n- **[CLAUDE_WIKI_INSTRUCTIONS.md](CLAUDE_WIKI_INSTRUCTIONS.md)** - Bitbucket wiki formatting guidelines for Claude agents\n- **[CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md)** - Complete guide for CEF client application development\n- **[README.md](README.md)** - This file\n\n### Python Tools\n\n- **[analyze_build_output.py](analyze_build_output.py)** - Analyze and format ninja build output with error index\n- **[analyze_coverage_output.py](analyze_coverage_output.py)** - Analyze LLVM coverage reports and identify coverage gaps\n- **[analyze_patch_output.py](analyze_patch_output.py)** - Analyze and format `patch_updater.py` output with file movement detection\n- **[patch_utils.py](patch_utils.py)** - Shared utilities for patch analysis tools (file movement detection)\n- **[verify_patch.py](verify_patch.py)** - Verify that regenerated patches include all changes from reject files\n- **[format_wiki.py](format_wiki.py)** - Apply Bitbucket wiki formatting guidelines to markdown files (supports wildcards; also integrated into `../fix_style.py`)\n\n### Test Files\n\n- **[analyze_build_output_test.py](analyze_build_output_test.py)** - Unit tests for analyze_build_output.py\n- **[analyze_coverage_output_test.py](analyze_coverage_output_test.py)** - Unit tests for analyze_coverage_output.py\n- **[analyze_patch_output_test.py](analyze_patch_output_test.py)** - Unit tests for analyze_patch_output.py\n- **[patch_utils_test.py](patch_utils_test.py)** - Unit tests for patch_utils.py\n- **[verify_patch_test.py](verify_patch_test.py)** - Unit tests for verify_patch.py\n- **[format_wiki_test.py](format_wiki_test.py)** - Unit tests for format_wiki.py\n\n## Common Setup\n\nFor Chromium update workflows, run the setup script:\n\n```bash\ncd chromium/src/cef/tools\npython3 setup_claude.py\n```\n\nThis copies `CLAUDE.md.in` to the project root as `chromium/src/CLAUDE.md`, enabling Claude Code to understand the Chromium/CEF codebase structure.\n\n## Formatting Files\n\nThe `fix_style.py` tool in `//cef/tools/` formats C/C++, Python, and Markdown files:\n\n```bash\n# From chromium/src/cef/tools directory:\n\n# Format single markdown file\npython3 fix_style.py claude/CLAUDE_TEST_INSTRUCTIONS.md\n\n# Format all CLAUDE instruction files\npython3 fix_style.py claude/CLAUDE_*.md\n\n# Format all markdown files in claude directory\npython3 fix_style.py claude/*.md\n\n# Format all staged files (including markdown)\npython3 fix_style.py staged\n```\n\nThe markdown formatter applies [Bitbucket wiki formatting guidelines](CLAUDE_WIKI_INSTRUCTIONS.md) (blank lines before lists, 4-space indentation, etc.).\n\n## Tips for Working with Claude Code\n\nThese tips apply to both Chromium updates and client development:\n\n### 1. Provide Context\n\nAlways include relevant version numbers or distribution details:\n\n**For Chromium updates:**\n```\nOld version: 139.0.7258.0\nNew version: 140.0.7339.0\n```\n\n**For client development:**\n```\nCEF binary distribution: cef_binary_142.0.10+g29548e2+chromium-142.0.7444.135_macosarm64\n```\n\n### 2. Attach Relevant Files\n\nUse `@filename` to attach files Claude should read:\n\n- `@cef/tools/claude/patch_analysis.txt` - Analyzed patch output\n- `@cef/tools/claude/build_analysis.txt` - Analyzed build output\n- `@cef/tools/claude/CLAUDE_CHERRY_PICK_INSTRUCTIONS.md` - Cherry-picking upstream commits\n- `@cef/tools/claude/CLAUDE_CLIENT_INSTRUCTIONS.md` - Client development guide\n- `@cef/tools/claude/CLAUDE_SRC_PATCH_INSTRUCTIONS.md` - Applying Chromium commits as patches\n- `@cef/tools/claude/CLAUDE_TEST_INSTRUCTIONS.md` - CEF unit testing guide\n\n**Tip:** In large directory structures like `chromium/src`, the `@` syntax can be slow. Use `//` syntax for workspace-relative paths instead (e.g., `//cef/tools/claude/patch_analysis.txt`).\n\n### 3. Let Claude Work Systematically\n\nDon't interrupt mid-stream unless necessary. Claude will:\n\n- Create TODO lists\n- Work through items one by one\n- Report progress regularly\n- Ask for help when stuck\n\n### 4. Use Incremental Prompts\n\nFor large tasks, you can guide Claude incrementally:\n\n**For Chromium updates:**\n```\n1. \"Start fixing patches using @CLAUDE_PATCH_INSTRUCTIONS.md\"\n2. [Claude works for a while]\n3. \"Good progress. Continue with the remaining patches.\"\n4. [Claude finishes]\n5. \"Now let's fix build errors using @CLAUDE_BUILD_INSTRUCTIONS.md\"\n```\n\n**For unit testing:**\n```\n1. \"Create tests for the new feature using @CLAUDE_TEST_INSTRUCTIONS.md\"\n2. [Claude creates tests]\n3. \"Run the tests and fix any failures\"\n4. [Claude debugs and fixes]\n5. \"Good, now verify they work in both Chrome and Alloy styles\"\n```\n\n### 5. Ask for Summaries\n\nAfter a session:\n```\nPlease summarize all the changes you made, organized by category.\n```\n\nClaude can provide a detailed summary for documentation or commit messages.\n\n### 6. Use the Analyzers Proactively\n\nFor Chromium updates, run the analyzers yourself first to understand the scope:\n\n**For patches:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_patch_output.py patch_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > patch_analysis.txt\n```\n\n**For build errors:**\n```bash\n# From chromium/src/cef/tools/claude directory:\npython3 analyze_build_output.py build_output.txt \\\n  --old-version 139.0.7258.0 \\\n  --new-version 140.0.7339.0 \\\n  --no-color > build_analysis.txt\n```\n\nThen share the analysis files with Claude.\n\n## Getting Help\n\n### For Issues with Tools\n\n- Check the guide files and instruction files listed above for usage examples\n- Check analyzer script help: `python3 analyze_patch_output.py --help`\n\n### For Issues with CEF\n\n- CEF wiki: https://github.com/chromiumembedded/cef/blob/master/docs/README.md\n- CEF forums: https://magpcss.org/ceforum/\n- CEF issue tracker: https://github.com/chromiumembedded/cef/issues\n\n### For Issues with Claude Code\n\n- Claude Code documentation: https://docs.claude.com/claude-code\n- Improve prompts with more context and specific examples\n- Break large tasks into smaller, more manageable pieces\n\n## Contributing\n\nIf you improve these tools or instructions:\n\n1. Test with a real Chromium update, client development task, or unit testing workflow\n2. Document what you changed and why\n3. Update the appropriate guide ([CHROMIUM_UPDATE.md](CHROMIUM_UPDATE.md), [CLIENT_DEVELOPMENT.md](CLIENT_DEVELOPMENT.md), or [CLAUDE_TEST_INSTRUCTIONS.md](CLAUDE_TEST_INSTRUCTIONS.md))\n4. Share improvements with the CEF community\n\n## License\n\nThese tools are part of the CEF project and follow the same license as CEF (BSD license).\n\n<!-- File: tools/debug/ax_viewport_collapse/README.md (Tokens: ~617 | Category: plugin-manifest) -->\n# ax_viewport_collapse Debug Tools\n\nManual verification tools for the `ax_viewport_collapse` CefBrowserSettings feature.\nThese connect to a running cefclient via CDP to inspect the accessibility tree.\n\n## Prerequisites\n\n```\npython3 -m pip install websocket-client\n```\n\n## Usage\n\n### 1. Launch cefclient with remote debugging\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\n```\n\nThe `--ax-viewport-collapse` flag maps to `CefBrowserSettings.ax_viewport_collapse = STATE_ENABLED` in cefclient.\n\nTo load the test page directly:\n\n```\ncefclient.exe --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse --url=file:///<path>/test_viewport_collapse.html\n```\n\n### 2. Run the verification script\n\n```\npython3 verify_viewport_collapse.py\n```\n\nOr navigate to a URL first:\n\n```\npython3 verify_viewport_collapse.py --url https://example.com\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `--host` | CDP host (default: `127.0.0.1`) |\n| `--port` | CDP port (default: `9222`) |\n| `--url` | Navigate to URL before fetching tree |\n| `--raw` | Print full JSON response instead of summary |\n\n### Comparing with/without collapse\n\nRun two cefclient instances on different ports:\n\n```\ncefclient.exe --cache-path=<path1> --remote-debugging-port=9222 --remote-allow-origins=* --ax-viewport-collapse\ncefclient.exe --cache-path=<path2> --remote-debugging-port=9223 --remote-allow-origins=*\n```\n\n```\npython3 verify_viewport_collapse.py --port 9222 --raw > with.json\npython3 verify_viewport_collapse.py --port 9223 --raw > without.json\ndiff with.json without.json\n```\n\n### Expected output (with collapse enabled)\n\n```\nAX Tree Summary\n============================================================\nTotal nodes returned:  77\n  Ignored:             3\n  Full (with children):70\n  Summary (collapsed): 4\n\nCollapsed summary nodes (off-screen landmarks/headings):\n------------------------------------------------------------\n  region: \"Content preferences\"\n  region: \"Audio quality\"\n  region: \"Display\"\n  region: \"Storage\"\n```\n\nOff-screen landmark sections appear as leaf nodes with role + name only. In-viewport nodes are fully serialized with children.\n\n## Files\n\n- `verify_viewport_collapse.py` — CDP script that calls `Accessibility.getFullAXTree()` and prints a summary or raw JSON\n- `test_viewport_collapse.html` — Test page with 6 landmark sections, 2 in viewport and 4 pushed off-screen by a spacer\n\n<!-- File: tools/gpt/README.md (Tokens: ~1450 | Category: plugin-manifest) -->\n# GPT Instructions for CEF Updates\n\nUse these guides when asking a coding agent to update CEF patches or fix build\nerrors during a Chromium update. The GPT guides give Sol a short overview of\nwhat to do and how to verify the result. They link to the existing Claude\nguides for detailed commands, examples, and troubleshooting.\n\n## Choosing a model\n\n| Model | Starting effort | Guides to use |\n| --- | --- | --- |\n| GPT-6.1 Sol | Low | The GPT guides in this directory |\n| GPT-5.6 Terra | Choose for your task | The Claude guides in `cef/tools/claude/` |\n\nFor Sol, start with low effort and use the Sol examples below. The agent can\nconsult the linked Claude guides as it works. For Terra, use the Terra examples,\nwhich point directly to the detailed Claude guides. Those guides work with\nother models despite their filenames.\n\nSelect the model and effort in your coding agent before sending the prompt.\nThe instruction files describe the work; model selection is a separate setting.\n\nThese recommendations are a starting point for trying the workflows on real\nupdates. Adjust the GPT model and reasoning effort to balance speed and cost\nwhile meeting the same completion checks. Check whether the agent covers every\nfailed file, preserves CEF behavior, and saves source fixes into the patches.\nIf Sol gets stuck on a particular issue or cannot explain why a behavioral\nchange is correct, try that issue again at medium effort. When comparing speed\nand cost, include any follow-up work needed to correct the result.\n\n## Getting started\n\nBefore launching the agent, use the existing Chromium update guide to prepare\nyour checkout and the analysis for the phase you're working on:\n\n1. Review the [complete update workflow](../claude/CHROMIUM_UPDATE.md#complete-update-workflow)\n   for the order of checkout updates, patch repairs, builds, and testing.\n2. Check the [prerequisites](../claude/CHROMIUM_UPDATE.md#prerequisites) and\n   [setup](../claude/CHROMIUM_UPDATE.md#setup): you'll need a Chromium checkout\n   with CEF integration, Python 3, and the appropriate build configuration.\n   The `setup_claude.py` step installs context for Claude Code; it is not a\n   prerequisite for using the GPT prompts.\n3. For patch repairs, follow [Phase 1: Fixing Patches](../claude/CHROMIUM_UPDATE.md#phase-1-fixing-patches)\n   to capture `patch_updater.py` output and generate `patch_analysis.txt` with\n   your old and new Chromium versions. Then use the patch prompt below.\n4. Once the patches apply cleanly, follow [Phase 2: Fixing Build Errors](../claude/CHROMIUM_UPDATE.md#phase-2-fixing-build-errors)\n   to capture a build of your chosen target and generate `build_analysis.txt`.\n   Then use the build prompt below.\n\nStart your coding agent from the `chromium/src` checkout root. Copy one of the\ncomplete prompts below, then replace the Chromium versions and analysis path\nwith yours. For a build task, also set your output directory and build target.\nAll paths in the prompts are relative to `chromium/src`.\n\nUse the analysis files produced by the existing tools in `cef/tools/claude/`:\n\n- `patch_analysis.txt` lists failed patches and files.\n- `build_analysis.txt` lists build errors and points to the relevant sections\n  of `build_output.txt`.\n\nThe build examples include permission to fix Chromium files outside `cef/`\nwhen custom CEF patches cause their build failures. Keep that instruction if\nit applies to your update: it tells the agent to save those fixes into the\nassociated CEF patches and overrides the detailed build guide's usual scope.\n\n## Example prompts for Sol at low effort\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/gpt/GPT_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. Fix those build\nerrors and re-save the associated CEF patch files using\ncef/tools/gpt/GPT_PATCH_INSTRUCTIONS.md.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n\n## Example prompts for Terra\n\n### Update patches\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease update patches from 154.0.8037.0 to 156.0.8078.0\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md\nWhen a patch has multiple failed files you MUST check all of the files.\n\nHere's the patch output analysis: cef/tools/claude/patch_analysis.txt\n```\n\n### Fix build errors\n\n```text\nWork from the chromium/src checkout root; all paths below are relative to it.\n\nPlease fix build errors for the 154.0.8037.0 to 156.0.8078.0 update\nRead and follow the instructions in:\ncef/tools/claude/CLAUDE_BUILD_INSTRUCTIONS.md\n\nBuild output directory: out/Debug_GN_arm64\nBuild target: cef\n\nIMPORTANT: Some .cc files outside of cef may also have build errors after\nthe Chromium update, due to the custom CEF patches applied. You should also\nfix those build errors and re-save the associated CEF patch files using\ncef/tools/claude/CLAUDE_PATCH_INSTRUCTIONS.md. This extends the build\nguide's default restriction to files under cef.\n\nHere's the build error analysis: cef/tools/claude/build_analysis.txt\n\nIMPORTANT: Do not try to read all of cef/tools/claude/build_output.txt. Use\nthe positional markers from cef/tools/claude/build_analysis.txt to read\nrelevant sections ONLY.\n```\n</yakaai_skills>"}