Struct ShellBuilder 

pub struct ShellBuilder { /* private fields */ }

Implementations

impl ShellBuilder

pub fn app_name(self, name: &str) -> Self

pub fn main_label(self, label: &str) -> Self

pub fn hardening(self, h: Hardening) -> Self

pub fn hardening_script(self, scope: HardeningScript) -> Self

Select DOM script injection scope for the full plugin (default: all frames). Native hardening & navigation policy still apply when the script is off.

pub fn devtools_policy(self, p: DevToolsPolicy) -> Self

Who may use DevTools. The default, DevToolsPolicy::Denied, makes no webview of the app inspectable. DevToolsPolicy::ContentOnly is a named allowance for an app that renders opened content (ViewRight) and must also register that content with ShellBuilder::content_webview. The policy applies whichever modules are installed.

pub fn content_webview(self, c: ContentWebview) -> Self

Register a webview that renders opened content as inspectable under DevToolsPolicy::ContentOnly. The main webview can never be registered, and setup fails with a typed DevToolsError when the content webview could reach the app’s IPC.

pub fn nav_policy(self, p: NavPolicy) -> Self

pub fn internal_scheme(self, scheme: &str) -> Self

Treat scheme as the app’s own content: the webview loads it in place. Adds to nav_policy whatever order they are called in. See NavPolicy::with_internal_scheme.

Panics

Panics on a scheme that is empty, malformed, or a web or script scheme (http, https, file, javascript, …): a programmer error at startup, like an invalid app id.

pub fn opener(self, o: impl ExternalOpener) -> Self

Replace the system link handler (tests, or an app that routes links itself).

pub fn single_instance(self, on: bool) -> Self

pub fn close_to_tray(self, on: bool) -> Self

Closing the main window hides it; the app keeps running in the tray until Quit.

pub fn close_behavior(self, behavior: CloseBehavior) -> Self

What closing the main window does. The last of close_to_tray and close_behavior wins. CloseBehavior::HideToBackground is for an app with no tray: it leaves the Dock while hidden on macOS and is reachable from wherever the host reveals it (a menu-bar item, a notch, a hotkey, a second launch).

pub fn on_visibility( self, f: impl Fn(&AppHandle<Wry>, Visibility) + Send + Sync + 'static, ) -> Self

Called after the main window is hidden (close, tray toggle) or revealed (tray, second launch, Dock reopen, opened URL), on the thread that raised the event. Runs after the shell’s own activation-policy change, so a host can drive its own policy with close_to_tray(true) instead of HideToBackground.

pub fn never_show(self, on: bool) -> Self

Host-declared “never show”: the shell shows, unminimises and focuses no window under any event (reopen, opened URL, second launch, show-on-ready, tray, the window command, windows::open/reveal, window-state restore), and on macOS the activation policy is set to Prohibited at plugin setup, before any window exists. Absolute: it beats show_on_ready, second_instance_reveal and every other visibility option. Default off. See also ShellBuilder::never_show_env. The host’s own direct window calls are outside the shell.

pub fn never_show_env(self, name: &str) -> Self

Register an environment variable that means never-show for this process when it is set to exactly 1, true, yes or on (ASCII case-insensitive; anything else, including empty, 0 and unrecognised text, is off; read at each reveal, so a harness can set it before launch). Call it once per name (ScrapeRight: RIGHTKIT_QA_NATIVE_REAL).

Panics

Panics on an empty name or one containing = or NUL: a programmer error at startup.

pub fn never_show_env_value(self, name: &str, expected: &str) -> Self

Register an environment variable that means never-show only when it is set to exactly expected (case-sensitive, no trimming); any other value, or unset, is off. For a harness that uses its own token.

Panics

Panics on an empty name (or one containing = or NUL) or an empty expected.

pub fn reveal_on_reopen(self, on: bool) -> Self

Whether a macOS Dock reopen with no visible window, and an OS-delivered URL or file (RunEvent::Opened), reveal the main window (default on). Off: both still deliver their links and nothing is shown, unminimised or focused. Also off when Module::RevealOnReopen is not installed.

pub fn qa_instance_exempt(self, on: bool) -> Self

A launch with RIGHTKIT_QA_HIDDEN=1 neither claims the primary nor forwards to the running instance, so a hidden QA copy never reveals the user’s app and is never revealed by it. Default off (a hidden QA launch arbitrates like any other).

pub fn second_instance_reveal( self, f: impl Fn(&AppHandle<Wry>, &[String], &str) -> bool + Send + Sync + 'static, ) -> Self

Keep the default second-launch behaviour (the second-instance event and deep links) but let the host decide whether it reveals and focuses the main window: f returns true to reveal. Ignored when ShellBuilder::on_second_instance replaces the default.

pub fn quit_drain(self, on: bool) -> Self

Let the renderer drain before the app exits. A quit request (tray Quit, Cmd+Q, the last window closing with a webview still alive) then emits rightkit-shell://quit-requested instead of exiting, and the app exits when the renderer calls rk_shell_finish_quit or after quit::DEFAULT_QUIT_DRAIN_BOUND (15 s), whichever comes first. Off by default: quit is immediate. rk_shell_quit (and shell.quit({force: true})) stays immediate either way.

pub fn quit_drain_bound(self, bound: Duration) -> Self

ShellBuilder::quit_drain with the host-side bound set (clamped to quit::MAX_QUIT_DRAIN_BOUND, 120 s). Give the renderer’s own quitTimeoutMs (10 s by default) less than this so its timeout reports before the host gives up.

pub fn frameless(self, on: bool) -> Self

Frameless chrome for windows created through windows::builder/open (see frameless).

pub fn show_on_ready(self, on: bool) -> Self

Show the main window when its webview is ready (default on). Calling this is an explicit visibility decision: RIGHTKIT_QA_HIDDEN no longer overrides it. --background still does.

pub fn state_dir(self, dir: PathBuf) -> Self

Directory for window-state.json (default: <app data dir>/shell).

pub fn deep_link_scheme(self, scheme: &str) -> Self

URL schemes this app accepts as deep links (myapp for myapp://...).

pub fn menu(self, m: MenuSpec) -> Self

pub fn tray(self, t: TraySpec) -> Self

pub fn autostart_options(self, options: AutostartOptions) -> Self

Login-item options: the launch arguments, macOS LowPriorityIO, and removing the entry tauri-plugin-autostart wrote (see autostart).

pub fn on_stall(self, f: impl Fn(&StallReport) + Send + Sync + 'static) -> Self

Called once per stall episode with the stall duration, on the watchdog thread (a host can write a hang dump here). Applies to the watchdog config in place: call it after ShellBuilder::watchdog, or it has no effect. No effect when the watchdog is disabled.

pub fn watchdog(self, w: Option<WatchdogConfig>) -> Self

pub fn on_second_instance( self, f: impl Fn(&AppHandle<Wry>, &[String], &str) + Send + Sync + 'static, ) -> Self

Rust-side handler for custom menu item clicks (the event is always emitted too). Replace the default second-launch behaviour (event + reveal the main window) with f, which receives the first instance’s handle, the second launch’s argv and its cwd, and fully owns focus. Arbitration is unchanged. URLs on that argv still reach open_url handlers and open_url::current_urls before f runs.

pub fn on_menu( self, f: impl Fn(&AppHandle<Wry>, &str) + Send + Sync + 'static, ) -> Self

pub fn stream_protocol(self, scheme: &str, policy: StreamPolicy) -> Self

Serve broker-granted files over a ranged custom protocol: <scheme>://localhost/<id> with the id from rk_shell_stream_grant (see stream). Off unless this is called.

pub fn site_protocol(self, scheme: &str, policy: SitePolicy) -> Self

Serve allowlisted subresources of granted site roots over <scheme>://localhost/<token>/<path> (see site). Granted with the rk_shell_site_grant command. Off unless this is called.

pub fn clipboard_purge_after(self, age: Duration) -> Self

Age after which clipboard temp images are purged (default one hour; see clipboard).

pub fn clipboard_options(self, options: ClipboardOptions) -> Self

Read-side clipboard options for rk_shell_clipboard_read and rk_shell_clipboard_item: the Windows bitmap preference and the opt-in capture of unknown pasteboard types (see clipboard::ClipboardOptions). The default captures no unknown types and prefers PNG.

pub fn recovery(self, spec: RecoverySpec) -> Self

Enable crash-safe setup recovery commands (see recovery).

pub fn webview_idle(self, suspend_after: Duration) -> Self

Suspend the main webview after it has been hidden this long (see idle). Off by default.

pub fn webview_idle_options(self, options: IdleOptions) -> Self

ShellBuilder::webview_idle with the full option set: the per-host timeout (IdleOptions::suspend_after, default idle::DEFAULT_SUSPEND_AFTER), starting the timer when the main window is minimised, hiding the WebView2 controller when the timer fires instead of at once, and whether idle events are emitted where nothing is suspended. A later webview_idle(d) replaces only the timeout.

pub fn webview_idle_on_error( self, f: impl Fn(&IdleFailure) + Send + Sync + 'static, ) -> Self

Receive suspend and resume failures of the main webview (see idle::IdleFailure). Without this, platform failures are silent.

pub fn webview_idle_on_transition( self, f: impl Fn(&IdleTransition) + Send + Sync + 'static, ) -> Self

Receive one idle::IdleTransition each time the main webview is really suspended or resumed (window label and elapsed time), for the host’s log. Without this nothing changes.

pub fn cache_dir(self, dir: PathBuf) -> Self

App cache directory to keep usable (default: Tauri’s app cache dir).

pub fn repair_cache(self, on: bool) -> Self

Repair a dangling symlink / stray file at the cache directory on startup (default on; default off under lifecycle_only, where this call turns it on).

pub fn on_presence( self, f: impl Fn(&AppHandle<Wry>, PresenceState) + Send + Sync + 'static, ) -> Self

Rust-side hook for automatic presence changes (meeting started, fullscreen app, …).

pub fn build(self) -> Shell