feat(config): allow macOS fullscreen and transparent APIs to be enabled independently

[tenderdeve]

Closes #15487

macOSPrivateApi currently couples two unrelated capabilities: it enables the WKWebView fullscreen API and transparent webview backgrounds. Apps that only need fullscreen are forced to also opt into the transparent-background private API. wry already exposes these as separate fullscreen / transparent features, so this splits them at the Tauri layer too.

Changes

• New config options app > macOS > fullscreenApi and app > macOS > transparentBackgroundApi.
• New Cargo features macos-private-api-fullscreen (→ wry/fullscreen) and macos-private-api-transparent (→ wry/transparent).
• macOSPrivateApi kept as-is; it now enables both sub-features, so existing configs are unchanged.
• AppConfig::features() emits only the sub-feature(s) the config actually needs.
• Transparent-only cfg gates in tauri/tauri-runtime-wry retargeted to macos-private-api-transparent; fullscreen is compile-time via wry/fullscreen.
• Regenerated config schema.

Testing

• cargo test -p tauri-utils (config tests pass).
• cargo check -p tauri -p tauri-runtime-wry under each of the three feature combinations.

[velocitysystems]

Great work @tenderdeve. I also know another contributor was looking into this. Any thoughts or feedback @polw1?

[velocitysystems]

Recommend we match the naming of the crate feature flags:

• privateApiFullscreen
• privateApiTransparent

Prefixing them with privateApi* makes it immediately obvious the user is opting into a private API.

[polw1]

One thing about this feature mapping:

I understand this is technically fine today because this is in tauri-runtime, but at the same time, reading that the new transparent-only feature enables the old macos-private-api feature can feel a bit confusing at first.

It also means tauri-runtime/macos-private-api effectively has to keep meaning “transparent support”.

Maybe that tradeoff is perfectly fine if we do not expect more macOS private API gates in tauri-runtime.

But from an API design perspective, I wonder if it would be clearer to mirror the split in tauri-runtime too and keep the old feature as an alias:

macos-private-api = ["macos-private-api-transparent"]
macos-private-api-transparent = []

That would keep compatibility while making the mapping read more directly:

tauri/macos-private-api-transparent
-> tauri-runtime/macos-private-api-transparent
-> tauri-runtime-wry?/macos-private-api-transparent
-> wry/transparent

Not a blocker from my side, mostly a naming/design tradeoff that maintainers may have a better feel for

[polw1]

Should we also update the crate-level feature docs in crates/tauri/src/lib.rs?

The existing macos-private-api feature is documented there, but these two new public features (macos-private-api-fullscreen and macos-private-api-transparent) are not listed yet.

Since users can now enable them directly, it may be useful to document them next to the existing legacy macos-private-api entry so they show up clearly in the generated crate docs

[tenderdeve]

thanks for the review both

@polw1 added the docs for the two new features in fea51b2, sat them right next to the existing macos-private-api entry in lib.rs.

re mirroring the split into tauri-runtime - i left it on the umbrella name because tauri-runtime's own gates (window.rs / webview.rs) still cfg on macos-private-api, so making it read -transparent all the way down means renaming those cfg attrs too. don't mind doing that but since you said it's non-blocking / a maintainer-feel thing i'll leave that call to them rather than touch the runtime gates unprompted.

@velocitysystems the keys currently sit under app > macOS > { fullscreenApi, transparentBackgroundApi } and are documented as private-api opt-ins. can rename to privateApiFullscreen / privateApiTransparent no problem, just want a maintainer ok first since it's public config schema. will change it as soon as there's a thumbs up.

[FabianLars]

i think splitting it in tauri-runtime makes sense (though i doubt we'll see more uses of private apis there)

don't care where the keys are, i can see both working so i'll leave that to who was pinged :P
we probably should mark the old umbrella key as deprecated though (check minimum_webview2_version for an example) - agreed? @velocitysystems

[velocitysystems]

@velocitysystems the keys currently sit under app > macOS > { fullscreenApi, transparentBackgroundApi } and are documented as private-api opt-ins. can rename to privateApiFullscreen / privateApiTransparent no problem, just want a maintainer ok first since it's public config schema. will change it as soon as there's a thumbs up.

@tenderdeve I'd recommend privateApiFullscreen / privateApiTransparent as siblings of macOSPrivateApi, not app.macOS.*:

1. We already have bundle > macOS. Adding a second configuration object is unecessary complexity.
2. Flat privateApi* keys keep the "you're opting into a private API" signal in the name and map 1:1 to the Cargo features.

i think splitting it in tauri-runtime makes sense (though i doubt we'll see more uses of private apis there). Don't care where the keys are, i can see both working so i'll leave that to who was pinged :P we probably should mark the old umbrella key as deprecated though (check minimum_webview2_version for an example) - agreed? @velocitysystems

@FabianLars Agreed. Please see deprecated pattern @tenderdeve.

[tenderdeve]

Pushed f749171 addressing all the feedback:

@velocitysystems renamed the granular opt-ins to flat privateApiFullscreen / privateApiTransparent as siblings of macOSPrivateApi (dropped the nested app.macOS object entirely), so they map 1:1 to the Cargo features. Also marked macOSPrivateApi #[deprecated(since = "2.10.0")] following the minimum_webview2_version pattern — schema now carries "deprecated": true. Umbrella still enables both.

@polw1 mirrored the split into tauri-runtime as you suggested: added macos-private-api-transparent and kept macos-private-api = ["macos-private-api-transparent"] as an alias, and pointed the runtime cfg gates + tauri-runtime-wry at the -transparent feature so the mapping reads straight through. The new features are already documented next to the legacy entry in lib.rs.

@FabianLars deprecation + runtime split both in.

Checked green with macos-private-api-fullscreen, macos-private-api-transparent, and the umbrella macos-private-api; tauri-utils test_defaults passes.

[velocitysystems]

Looks good. Passing over to @FabianLars for a final review. Thanks @tenderdeve!

[FabianLars]

ngl i kinda like the app > macOS object but i'm also considering to remove the flag for transparency since that apparently never caused issues in store reviews.

but yeah, i'm okay with keeping it top level, but then i'd prefix them with macos again, eg macOSPrivateApiFullscreen

[FabianLars]

additionally, seems like on recent-ish macos/ios versions the fullscreen api is not private anymore: https://developer.apple.com/documentation/webkit/wkpreferences/iselementfullscreenenabled
if that works, i'd remove the private api in favor of a version check, not the only api that's behind a version check.

Edit: it's not actually the same property but from its name it sounds like it does what we need.

[velocitysystems]

ngl i kinda like the app > macOS object but i'm also considering to remove the flag for transparency since that apparently never caused issues in store reviews.

but yeah, i'm okay with keeping it top level, but then i'd prefix them with macos again, eg macOSPrivateApiFullscreen

@FabianLars I think my suggestion may have been misunderstood. I was advocating for them to be under bundle > macOS since: (a) this already exists, (b) is macOS specific. I agree we don't want them just under app. If they are parented under the macOS key then they don't require the macOS prefix.

[FabianLars]

nah, under bundle > macOS it makes no sense imo. That's for bundle(r) (as-in tauri-bundler) stuff, it generally shouldn't contain runtime/config things, but the private apis are a bit of a grey zone, they could maybeee fit into both categories.

[velocitysystems]

nah, under bundle > macOS it makes no sense imo. That's for bundle(r) (as-in tauri-bundler) stuff, it generally shouldn't contain runtime/config things, but the private apis are a bit of a grey zone, they could maybeee fit into both categories.

@FabianLars What about build > macOS? E.g.

[FabianLars]

That would for me as well i think.

i'm also considering to remove the flag for transparency since that apparently never caused issues in store reviews.

additionally, seems like on recent-ish macos/ios versions the fullscreen api is not private anymore: https://developer.apple.com/documentation/webkit/wkpreferences/iselementfullscreenenabled
if that works, i'd remove the private api in favor of a version check, not the only api that's behind a version check.

@Legend-Master How do you feel about yet another breaking change in 2.12? 😂 (meaning raising the minimum macos version for the webview element fullscreen functionality)

(also wouldn't mind your opinion on the block for the 2 apis here if we'll add them)

[tenderdeve]

Thanks both — following the thread, sounds like the landing spot is build > macOS > { fullscreenApi, transparentBackgroundApi } (unprefixed, since the macOS parent already carries the private-api signal), with app > macOSPrivateApi staying as the deprecated umbrella. Happy to move the keys there — it's a contained change from where they sit now.

Before I churn the schema again though: @FabianLars you also raised possibly dropping the transparency flag and swapping the fullscreen private API for a macOS-version check on isElementFullscreenEnabled, pending @Legend-Master's take on the 2.12 breaking change. That would change whether these two keys exist at all, so I'd rather not rework the config twice.

So: should I go ahead and relocate to build > macOS now (keeping both flags), or hold until the keep-vs-version-check question is settled? Either's fine by me — just say the word.

[Legend-Master]

If the new API works, I think we can really keep the current macOSPrivateApi so that full screen would work on the right versions without the flag and if you want it to work on older versions, you enable both private APIs. That being said, I'm not entirely sure how impactful 1 private API vs 2 would be. Does Apple remove/change old private APIs on new versions or it's just the store reviews?

[FabianLars]

In theory they can remove private apis but I've yet to see that happen. Though aside from those we use, it's quite rare to use private apis I think.
This is really primarily about the store reviews. But at least the transparency one always went through.

And if these 2 get removed that's also fine because both basically just set a Map value, we don't even use an actual api.

[tenderdeve]

Gentle nudge on this one so it doesn't go stale — sounds like the thread landed on two possible directions:

1. Keep both flags, just move them to build > macOS > { fullscreenApi, transparentBackgroundApi } (unprefixed) with macOSPrivateApi staying as the deprecated umbrella.
2. Drop the two flags entirely — transparency never tripped store review, and fullscreen can ride a macOS version check on isElementFullscreenEnabled instead.

Both are small changes from where the PR sits now; I just don't want to churn the schema twice. Happy to push whichever you land on — @FabianLars @Legend-Master @velocitysystems, what's the call?

[FabianLars]

Sorry i forgot to update you here. After some more research, and realizing that we already had an unguarded private property in wry for a while, i decided to see how things go without the feature flags: tauri-apps/wry#1779

[tenderdeve]

Following up now that wry#1779 landed — nice, fullscreen working without the private API changes the picture here quite a bit.

If the plan is to drop the flags entirely (fullscreen riding the version check, transparency going unguarded since it never tripped store review), then this split PR mostly becomes the wrong direction and I'd rather not churn the schema toward build > macOS just to tear it out again.

So before I touch anything else: do you want to

1. drop both flags — in which case I'm happy to close this and, if useful, open a fresh PR that removes macOSPrivateApi (or keeps it as a deprecated no-op) and wires the tauri side to the new wry behavior, or
2. still land the split as an interim.

Whichever you prefer @FabianLars — just don't want to guess and redo the schema twice.

[FabianLars]

In tauri 2.12 macOSPrivateApis will become no-op and marked as deprecated. This indeed makes this PR completely obsolete.

[velocitysystems]

Thanks @FabianLars. I've updated #15487 as resolved by #tauri-apps/wry#1779.