Skip to content

Opt-in Blink engine (CEF) on macOS, phase 1 - #28

Draft
ipfizz wants to merge 15 commits into
mainfrom
feat/blink-cef
Draft

ipfizz wants to merge 15 commits into
mainfrom
feat/blink-cef

Conversation

@ipfizz

@ipfizz ipfizz commented Sep 28, 2026

Copy link
Copy Markdown
Owner

Adds an opt-in Blink engine for macOS. It runs Chromium's renderer through CEF instead of WKWebView. As with our pinned WebKit engines, the engine is not bundled into the app: it's a separate build that lives in the engine store, and a project pins it by id. The design is decision D048 in the internal notes. This is experimental and phase 1: macOS only, with gaps listed below.

How it works

  • cef is a new engine family, so a Blink build has an ordinary engine id (for example cef-154.0.28-154.0.8037.58-bunmaska1-macos-arm64). It's installed and pinned like any other engine; BUNMASKA_ENGINE_ID works as an alias of BUNMASKA_WEBKIT_ID.
  • When the pinned engine is Blink, platform/index.ts starts the CEF backend. Blink draws the page; bunmaska's normal macOS window code still handles the window itself.
  • Everything else still uses the macOS services: menus, tray, dialogs, clipboard, notifications and so on.
  • The CEF C API is driven through bun:ffi, with a small C shim that Bun's built-in compiler (TinyCC) builds when the app starts. CEF can call back from any thread, and the shim hands those calls to the JavaScript thread.
  • The page side goes through the Chrome DevTools protocol, over the connection CEF provides inside the process:
    • the preload runs in its own isolated world;
    • IPC goes through a binding that only the main frame's isolated world can call;
    • executeJavaScript, capturePage, printToPDF and sendInputEvent are implemented.
  • The injected scripts come from the shared platform/web-scripts.ts, so preload, contextBridge and IPC behave as on the WebKit backends.
  • Chromium's background calls to Google are switched off: network time, search preconnect, component and model downloads, secure DNS, and autofill lookups. The account-list check can't be switched off, so it is sent to an invalid address that fails before any network request.
  • tools/engine/build-cef-engine.ts builds an engine from the official CEF download: it picks a build matching our pinned CEF API version, and compiles a small helper app with clang -std=c17 -pedantic -Werror.

Known gaps (fail loudly instead of acting on the wrong engine)

  • session.cookies and session.clearStorageData reject with UnsupportedPlatformError under Blink.
  • protocol.handle schemes are not served yet; a warning names them when a window is created.
  • bunmaska build refuses a macOS build pinned to Blink.
  • There is no renderer sandbox, cef_shutdown is skipped, and only macOS is supported.
  • Untested under Blink: modal dialogs and popup menus while a page is busy, frameless window dragging, and menu edit roles.

Review

  • A three-lens review covered native correctness, regressions to the default WebKit path, and security. It raised 12 findings; each was checked by a skeptic. All 12 held up; after merging duplicates, 9 distinct issues were fixed, each with a test where one is possible without the real engine. The most important:
    • Blink's profile now lives in userData/Blink. It used to sit next to requestSingleInstanceLock's lock files, which caused a roughly 20-second stall on launch.
    • A second launch no longer opens a stray Chrome browser window.
    • IPC is accepted only from the main frame.
    • The C shim and the dev bundle are written into private temporary folders.
  • The default WebKit path is unchanged: the WKWebView code moved verbatim into attachWebKitView, and the run loop is untouched. An engine only gets a drain hook.

Checks

  • macOS: bun run validate exits 0, with 1939 pass, 185 skip and 0 fail.
  • Tested by hand against the real engine, which CI doesn't have:
    • the full test app (render, isolated preload, IPC, network, executeJavaScript, capture, PDF, clean close) on both Blink and the system WebKit;
    • a relaunch and single-instance check.
  • The tests that need the real engine skip themselves when it isn't installed.

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant