Aqua WebKit

This is a backport of modern WebKit to OS X 10.9 Mavericks, suitable for replacing the system-installed WebKit. After replacing the system copies of /System/Library/WebKit.framework, /System/Library/JavaScriptCore.framework, and /System/Library/PrivateFrameworks/WebKit2.framework you will be able to use Safari 7 to browse the modern web.

Almost all backport code was generated by language models, sometimes with minimal oversight. This top-level readme is and always will be entirely human-authored.

Should You Use This?

As of this writing, the backport is still experimental, and installing it has the potential to impact almost any app on your machine. You may experience some wierdness, which you should report in the Issues tab on Github. You are expected to have Time Machine enabled in case anything goes wrong.

That said, this is already a sold port. It works with virtually all websites, including complex webapps like Figma and Google Meet.

If you previously deleted Safari, you can find a working copy of Safari 7 in the Applications folder of the Mavericks installer DMG (no special extraction necessary). If you previously upgraded to Safari 9, you will need to downgrade to Safari 7; doing this properly is currently beyond the scope of this documentation, but simply replacing Safari.app should basically work. An upcoming full release of the backport will include a way to automatically downgrade Safari 9.

Architecture

Notes

• The backport is fully self-hosted. Build on Mavericks; use on Mavericks.
• With the exception of the macOS SDK, all dependencies and build requirements are included in the repository.
• The backport is built using a modern clang compiler, a modern C++ standard library, and a modern macOS SDK.
• Video playback is handled by gstreamer, used upstream by WebKitGTK.
• Image decoding is handled by the same set of libraries used upstream by WebKitGTK (libpng, libjpeg-turbo, etc).
• WebCrypto is handled by libgcrypt, used upstream by WebKitGTK.
• Networking is largely handled by curl, used upstream by WebKit WinCairo. Data is still stored in CFNetwork containers for Safari compatibility. BoringSSL is used for TLS.
• Google's proprietary Widevine library will be automatically downloaded and patched at runtime to support protected media playback.

Guiding Principles

• Minimize upstream divergence. Wherever possible, polyfill outside of WebKit's codebase (e.g. in AquaWebKitSupport). There are two reasons for this:
  • Polyfills make it easy to merge changes from upstream in the future.
  • Polyfills ensure we are using battle-tested upstream logic over custom logic we wrote ourselves. A polyfill merely provides WebKit with the environment it expects.
• Minimize the amount of complex computer-generated code by using existing libraries where possible.

Building

Relative to the complexity of WebKit, building this project should be straightforward. Please try it! If you run into trouble, open an issue.

On a Mac or Virtual Machine running Mavericks with Apple's Command Line Tools installed:

1. Clone this repository.
   • To speed up this step, you may wish to use --depth N, where N is a reasonably small number, to fetch only the N most recent commits.
2. Place a copy of the MacOSX26.1.sdk adjacent to your cloned repository.
   • For example, if you cloned to ~/Developer/webkit, you would want to place the SDK at ~/Developer/MacOSX26.1.sdk.
   • Alternately, place the SDK wherever you want and remember to set the AQUAWEBKIT_SDK environment variable in a later step.
   • Officially, the SDK must be extracted from a recent copy of Xcode. Unofficially, just download it here.
3. Run AquaWebKitSupport/bootstrap.sh to extract/build the toolchain.
4. Run AquaWebKitSupport/build.sh to build WebKit.
   • On a reasonably fast machine, this will take hours, but not days. Consider letting it run over night.
   • Ccache is enabled and included in the toolchain. After you've built the project once, future rebuilds should be much faster.
5. If desired, run AquaWebKitSupport/install.sh to install the Frameworks on your system.

Contributing

This is a massive project, and contributions are appreciated!

Every (!) hunk that diverges from WebKit must include an AQUAWEBKIT marker comment. Think of these a little like unsafe blocks in Rust; we need them sometimes, but we'd much rather make a polyfill. Like converting unsafe code to safe, code that converts an upstream divergence to a polyfill is highly valued even if it has no functional benefit.

AI Guidelines

Fully handwritten code is greatly respected, and will be held in especially high regard!

Code generated by language models is also very much allowed in this backport. However, please take reasonable steps to ensure that the code you submit is correct and functional. This includes but is not limited to building and manually testing your code and running applicable test suites.

In general, please do not use AI in any written communication, including pull requests and bug reports. I enjoy talking to real people, not computers! If an issue is technically above your head such that you need an AI's assistance, please explain the problem from your perspective first (ie what do you experience) and then clearly demarcate AI-generated blocks.