fix(v2): select Safari WebKit by macOS deployment target - #5903
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR introduces a macOS build-time policy for Wails v2 that selects Safari’s staged WebKit frameworks (and embeds versioned DYLD search paths) when targeting macOS 12.3–12.x, while keeping the existing system-WebKit behavior for older targets and for macOS 13+.
Changes:
- Add
macOSBuildConfigparsing/validation forMACOSX_DEPLOYMENT_TARGETand (optionally)WAILS_MACOS_STAGED_FRAMEWORKS, enabling Safari-staged WebKit selection for macOS 12.3–12.x. - Inject staged framework linker flags (
-F…) and versioned DYLD runtime selection via-extldflagswhen applicable. - Propagate the deployment target consistently through CGO flags and the build environment, with unit tests for the selection logic.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| v2/pkg/commands/build/macos.go | New deployment-target parsing + Safari staged framework validation and external linker flag composition. |
| v2/pkg/commands/build/macos_test.go | Unit tests covering selection logic, validation failures, and linker-arg contents. |
| v2/pkg/commands/build/base.go | Wires the macOS build config into the build pipeline: -ldflags, CGO flags, and MACOSX_DEPLOYMENT_TARGET. |
Suppressed comments (1)
v2/pkg/commands/build/base.go:376
- The comment above the CGO_LDFLAGS upsert says the minimum macOS SDK is fixed to 10.13, but the code now sets -mmacosx-version-min from macOSConfig.deploymentTarget. Updating the comment will prevent future confusion when adjusting deployment targets.
if !strings.Contains(v, "-mmacosx-version-min") {
v += "-mmacosx-version-min=" + macOSConfig.deploymentTarget
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| cmd.Env = shell.UpsertEnv(cmd.Env, "MACOSX_DEPLOYMENT_TARGET", func(string) string { | ||
| return macOSConfig.deploymentTarget | ||
| }) |
| binary := filepath.Join(root, framework+".framework", "Versions", "A", framework) | ||
| if _, err := os.Stat(binary); err != nil { | ||
| return fmt.Errorf("Safari staged WebKit is incomplete: missing %s", filepath.Join(root, framework+".framework")) | ||
| } |
Context
On macOS Monterey 12.7.6, the system WKWebView/JavaScriptCore can be older than the WebKit that Safari has staged in:
Reasonix currently reaches JavaScript and RegExp features in markdownRemarkPlugins that Monterey's system engine cannot parse. The observed failure is:
It happens while the bundle is being parsed, before React mounts, so the user sees a black/error window. This is a native WebKit version skew, not a Reasonix application-logic bug. Adding more JavaScript shims or repeatedly rewriting individual expressions only moves the compatibility burden to every application.
What this PR changes
Wails now owns this macOS framework selection policy during the normal build:
The 12.3 boundary is intentional: the Safari staged framework set validated on Monterey declares macOS 12.3 as its minimum. Selecting it for 12.0–12.2 would produce an invalid deployment target rather than a supported binary.
The optional WAILS_MACOS_STAGED_FRAMEWORKS environment variable is available for controlled build/test environments; the default is Apple's standard staged-framework location.
Why this belongs in Wails
The policy is about how a Wails application is linked and launched, not about Reasonix's frontend. Keeping it here gives every Wails v2 application the same opt-in behavior through:
It also covers manual builds and CI builds without requiring each consumer to duplicate framework validation, -F flags, DYLD_VERSIONED_* flags, and CGO linker plumbing.
Compatibility evidence
This problem has repeatedly been addressed at the application layer:
Not every historical report has the same immediate trigger: for example, crossorigin failures are custom-scheme/CORS behavior, not JavaScript syntax. The common maintenance problem is that applications have to discover and encode WebKit-version quirks independently.
Maintenance impact
The paired Reasonix change is only five lines: it sets a 12.3 deployment-target default in its existing desktop build script and leaves all WebKit/linker policy to Wails. No Safari path, native linker flags, or Wails-specific compatibility test is added to the application.
Once this behavior is available in a released Wails version, the following Reasonix cleanup becomes possible as a separate, verifiable follow-up:
This separates permanent product behavior from compatibility debt and makes future WebKit policy fixes reusable across Wails applications.
Validation
Paired PR
Reasonix consumer PR: esengine/DeepSeek-Reasonix#7628
These two PRs should be reviewed and merged as a pair. The Reasonix PR deliberately contains only the deployment-target handoff; this PR contains the native WebKit policy.