refactor(cef): re-import clean CEF 147 headers; source generated headers from CEF_ROOT

The vendored src/include tree had drifted from upstream: a stale
internal/cef_types.h missing the CEF 147 CEF_API_ADDED(14700) ABI content
(new result codes, permission types, CPAIT enums) while the build links the
147 binary, plus AI cosmetic edits (em-dashes, license reflow), removed-upstream
headers (cef_extension*, base/cef_callback_list, cef_auto_reset, cef_ptr_util,
cef_tuple, ...), and checked-in generated release headers.

Re-import src/include cleanly from the upstream CEF source repository at the
exact build commit (chromiumembedded/cef@d58e84d = 147.0.10+gd58e84d), verified
byte-identical to all three platform binary distributions (Linux/macOS exact;
Windows exact after CRLF normalization).

The platform-generated headers are intentionally NOT vendored (they are produced
during CEF packaging and differ per platform): cef_version.h, cef_config.h,
cef_api_versions.h, cef_color_ids.h, cef_command_ids.h, cef_pack_resources.h,
cef_pack_strings.h, and base/internal/cef_net_error_list.h. They are still
required at compile time because upstream headers include them transitively
(e.g. cef_browser.h -> cef_command_ids.h; cef_api_hash.h -> cef_version.h;
cef_types.h -> cef_net_error_list.h), so they are now resolved from
CEF_ROOT/include:

- CMake lists CEF_ROOT after src/ on the include path (module, client_handler,
  cpp_utils, subprocess) so vendored source headers take precedence and only the
  generated headers fall through to the CEF SDK.
- automate.py --prebuilt-cef copies include/ into the prebuilt CEF_ROOT so it is
  a complete SDK; the copy is idempotent so a CI-cached prebuilt dir created
  before this change is repaired.

Also removes the unused capi/ headers and documents the reproducible header
re-import procedure in docs/Contributing-code.md ("Updating CEF version") so
future upgrades stay clean.

Verified on Linux: clean build, 85/85 unit tests, hello_world. Windows/macOS
rely on CI; their headers were verified byte-identical to the respective dists.

Addresses review feedback on PR cztomczak#691 (cztomczak/cefpython).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: linesight

CMakeLists.txt

@@ -252,6 +252,12 @@ target_include_directories(${MODULE_NAME} PRIVATE
     "${SRC_DIR}/extern"
     "${SRC_DIR}/extern/cef"
     "${PYX_STAGE_DIR}"
+    # After src/: resolves the platform-generated CEF headers that are not
+    # vendored in src/include (cef_version.h, cef_api_versions.h, cef_pack_*.h,
+    # cef_color_ids.h, cef_command_ids.h, cef_config.h,
+    # base/internal/cef_net_error_list.h). Vendored source headers in
+    # src/include take precedence because SRC_DIR is listed first.
+    "${CEF_ROOT}"
 )
 
 if(ENABLE_LINE_TRACING)

docs/Contributing-code.md

@@ -149,5 +149,67 @@ to add your name and encoded email.
 
 ## Updating CEF version
 
-If you want to update CEF version then take a look at
-[Issue #264](../../../issues/264)("Workflow when updating CEF version").
+For the general workflow see
+[Issue #264](../../../issues/264) ("Workflow when updating CEF version").
+
+### Re-importing the CEF headers
+
+cefpython compiles against the CEF headers vendored in `src/include/` (the
+include path starts at `src/`, so `#include "include/cef_*.h"` resolves there).
+On every CEF upgrade these headers must be re-imported cleanly from the upstream
+**CEF source repository** — not copied from the binary distribution — so they
+stay byte-identical to upstream and don't accumulate stale/edited content.
+
+`src/include/` holds only the stable, hand-written public headers. The
+following **generated** headers are intentionally *not* vendored; they are
+produced during CEF release packaging (and differ per platform), and are
+resolved at build time from `CEF_ROOT/include` instead:
+
+- `cef_version.h`, `cef_config.h`, `cef_api_versions.h`
+- `cef_color_ids.h`, `cef_command_ids.h`
+- `cef_pack_resources.h`, `cef_pack_strings.h`
+- `base/internal/cef_net_error_list.h`
+
+`tools/automate.py --prebuilt-cef` copies the distribution's `include/` into the
+prebuilt `CEF_ROOT` directory so those generated headers are available, and the
+CMake include path lists `CEF_ROOT` *after* `src/` so the vendored source
+headers always take precedence. The `capi/` C API headers are not used by
+cefpython and are not vendored either.
+
+Steps:
+
+1. Bump the version/hashes in `src/version/cef_version_{win,linux,macarm64}.h`.
+
+2. Find the CEF source commit — it is the `g<hash>` in the `CEF_VERSION`
+   string. For `147.0.10+gd58e84d+chromium-147.0.7727.118` the commit is
+   `d58e84d`.
+
+3. Fetch that exact source tree and replace `src/include/`:
+
+   ```bash
+   commit=d58e84d   # from CEF_VERSION above
+   curl -sL "https://codeload.github.com/chromiumembedded/cef/tar.gz/$commit" \
+       | tar xz
+   rm -rf src/include
+   cp -r "cef-$commit/include" src/include
+   # capi/ and base/internal/cef_net_error_list.h are placeholder stubs in the
+   # source tree (the stub #includes a Chromium path and is replaced with the
+   # real content during CEF packaging). Remove them so the build resolves the
+   # real versions from CEF_ROOT/include.
+   rm -rf src/include/capi
+   rm -f  src/include/base/internal/cef_net_error_list.h
+   # Drop any non-header docs the source tree ships under include/ (e.g. *.md):
+   find src/include -type f ! -name '*.h' ! -name '*.inc' -delete
+   ```
+
+   The remaining generated headers (`cef_version.h`, `cef_config.h`,
+   `cef_api_versions.h`, `cef_color_ids.h`, `cef_command_ids.h`,
+   `cef_pack_resources.h`, `cef_pack_strings.h`) do **not** exist in the source
+   tree at all — they are created during CEF packaging — so a clean source
+   import already excludes them and there is nothing to delete. They are
+   resolved from `CEF_ROOT/include` at build time.
+
+4. Sanity check: the vendored headers should be byte-identical to the same
+   files in the downloaded CEF binary distribution's `include/` (ignoring the
+   Windows distribution's CRLF line endings). Then rebuild and run the unit
+   tests (`unittests/_test_runner.py`).

src/client_handler/CMakeLists.txt

@@ -21,6 +21,8 @@ target_include_directories(client_handler PRIVATE
     "${CEFPYTHON_SRC_DIR}/common"
     "${CEFPYTHON_PYX_STAGE_DIR}"
     ${Python_INCLUDE_DIRS}
+    # After src/: platform-generated CEF headers not vendored in src/include.
+    "${CEFPYTHON_CEF_ROOT}"
 )
 
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux")

src/cpp_utils/CMakeLists.txt

@@ -8,6 +8,8 @@ target_include_directories(cpp_utils PRIVATE
     "${CEFPYTHON_SRC_DIR}/common"
     "${CEFPYTHON_PYX_STAGE_DIR}"
     ${Python_INCLUDE_DIRS}
+    # After src/: platform-generated CEF headers not vendored in src/include.
+    "${CEFPYTHON_CEF_ROOT}"
 )
 
 # Common browser-process flags come from cefpython_common_flags defined in the