127 lines
5.9 KiB
Markdown
127 lines
5.9 KiB
Markdown
# Hide Warp Dock Icon — Tech Spec
|
|
|
|
## Summary
|
|
|
|
Add a macOS-only `show_dock_icon` appearance setting that switches Warp between regular and accessory AppKit activation policies. When disabled, Warp is hidden from the Dock and Cmd-Tab while continuing to run.
|
|
|
|
## Relevant existing code
|
|
|
|
- `app/src/settings/app_icon.rs` — app icon settings namespace and generated settings state.
|
|
- `app/src/settings_view/appearance_page.rs` — Appearance settings UI.
|
|
- `app/src/appearance.rs` — runtime appearance/app icon setting handling.
|
|
- `app/src/lib.rs` — macOS `AppBuilder` setup before `app_builder.run`.
|
|
- `crates/warpui_core/src/platform/mod.rs` and `crates/warpui_core/src/core/app.rs` — platform delegate API.
|
|
- `crates/warpui/src/platform/mac/app.rs` — macOS app builder/run wiring.
|
|
- `crates/warpui/src/platform/mac/delegate.rs` — macOS platform delegate implementation.
|
|
- `crates/warpui/src/platform/mac/objc/app.{h,m}` — AppKit delegate and activation-policy calls.
|
|
|
|
## Design
|
|
|
|
### 1. Add a macOS Dock visibility setting
|
|
|
|
Add a generated setting under `AppIconSettings`:
|
|
|
|
- Name: `show_dock_icon`
|
|
- Type: `bool`
|
|
- Default: `true`
|
|
- Platform support: `SupportedPlatforms::MAC`
|
|
- Sync: disabled, matching app icon settings behavior
|
|
- Storage key: `ShowDockIcon`
|
|
- TOML path: `appearance.icon.show_dock_icon`
|
|
- Description: whether Warp is shown in the macOS Dock and Cmd-Tab switcher.
|
|
|
|
Keep this as a separate field from `app_icon`. Do not add a hidden variant to `AppIcon`, because `AppIcon` still describes artwork when the Dock icon is visible.
|
|
|
|
### 2. Apply the saved preference during launch
|
|
|
|
In `app/src/lib.rs`, after public preferences are available and before `app_builder.run`, read the saved `ShowDockIcon` value from `prefs_for_public_settings` using the generated setting helper, following the same pre-app-read pattern used by `ForceX11`.
|
|
|
|
Extend `warpui::platform::mac::AppExt` with `set_show_dock_icon_on_launch`, store the value in the macOS backend, and apply it in `warp_app_will_finish_launching`.
|
|
|
|
Initializing it before launch lets the AppKit layer apply accessory mode as early as practical, reducing visible Dock flicker for users who have already hidden the Dock icon.
|
|
|
|
### 3. Apply runtime setting changes
|
|
|
|
Handle the generated changed event alongside `AppIconState` in `AppearanceManager`. On `ShowDockIcon` changes, call the platform delegate to update Dock visibility immediately.
|
|
|
|
Add a platform delegate method such as `set_dock_icon_visible(visible: bool)`. Non-macOS implementations should be no-ops. The macOS implementation should dispatch to the main queue and call the Objective-C AppKit bridge.
|
|
|
|
### 4. macOS AppKit bridge
|
|
|
|
Add `-[WarpDelegate setDockIconVisible:]` in Objective-C. It should call:
|
|
|
|
- `NSApplicationActivationPolicyRegular` when `visible == YES`
|
|
- `NSApplicationActivationPolicyAccessory` when `visible == NO`
|
|
|
|
Return whether AppKit accepted the activation-policy change. If hiding fails, leave or restore the regular policy so Warp remains visible in the Dock.
|
|
|
|
### 5. Settings UI
|
|
|
|
Add a switch labelled "Show Warp in Dock" near the existing app icon controls in Appearance settings.
|
|
|
|
- Default checked state reflects `AppIconSettings::show_dock_icon`.
|
|
- Toggle dispatch updates `AppIconSettings.show_dock_icon`.
|
|
- Gate display/support via `is_supported_on_current_platform` from the setting metadata rather than compile-time `cfg` checks.
|
|
- Include search terms such as "dock", "cmd tab", and "app switcher".
|
|
|
|
## Behavior flows
|
|
|
|
### User hides the Dock icon
|
|
|
|
1. User opens Appearance settings and turns off Show Warp in Dock.
|
|
2. `AppIconSettings.show_dock_icon` is saved.
|
|
3. `AppearanceManager` receives the changed event.
|
|
4. The platform delegate applies accessory activation policy.
|
|
5. Warp disappears from the Dock and Cmd-Tab.
|
|
|
|
### User restores the Dock icon
|
|
|
|
1. User turns on Show Warp in Dock.
|
|
2. `AppIconSettings.show_dock_icon` is saved.
|
|
3. `AppearanceManager` receives the changed event.
|
|
4. The platform delegate applies regular activation policy.
|
|
5. Warp returns to the Dock and Cmd-Tab.
|
|
|
|
### Launch with hidden Dock icon
|
|
|
|
1. `app/src/lib.rs` reads `ShowDockIcon` before `app_builder.run`.
|
|
2. The macOS app builder stores `show_dock_icon_on_launch`.
|
|
3. `warp_app_will_finish_launching` applies the initial activation policy.
|
|
|
|
## Risks and mitigations
|
|
|
|
### Risk: users hide the Dock icon without a hotkey
|
|
|
|
Users can still reach existing visible windows, Mission Control, and other macOS window-management surfaces, but the main intended workflow is hotkey-driven.
|
|
|
|
Mitigation: keep the setting opt-in, default it to visible, and make the label explicit.
|
|
|
|
### Risk: AppKit rejects activation-policy changes
|
|
|
|
Mitigation: check the Objective-C return value. If hiding fails, leave or restore regular activation policy so Warp remains visible in the Dock.
|
|
|
|
### Risk: non-macOS no-op setting
|
|
|
|
Mitigation: mark the setting as macOS-only and gate the Appearance row with `is_supported_on_current_platform`.
|
|
|
|
## Test plan
|
|
|
|
Automated:
|
|
|
|
- Add settings/schema coverage ensuring `appearance.icon.show_dock_icon` exists, defaults to `true`, is macOS-only, and does not sync to cloud where practical.
|
|
- Add compile coverage for `warpui` macOS code paths in the existing macOS CI job.
|
|
|
|
Manual macOS:
|
|
|
|
- Toggle Show Warp in Dock off and verify Warp disappears from the Dock and Cmd-Tab.
|
|
- Verify configured global hotkeys still focus/show Warp while Dock visibility is disabled.
|
|
- Restart Warp with Show Warp in Dock disabled and verify the app starts in hidden-Dock mode.
|
|
- Toggle Show Warp in Dock back on and verify the Dock icon and Cmd-Tab entry return.
|
|
- Verify changing the selected app icon still updates Dock art when Show Warp in Dock is enabled.
|
|
- Verify non-macOS builds do not show an enabled no-op setting.
|
|
|
|
## Future considerations
|
|
|
|
- Consider a separate menu bar/status item recovery surface if user feedback indicates it is needed.
|
|
- Consider launch-at-login/background-start behavior as a separate feature for users who want Warp available only through hotkey after boot.
|