Crate ashlar_native 

Native OS features behind one small, safe API: file dialogs, the menu bar, the clipboard, keep-awake, files opened from the file manager, single instance, notifications, dock / taskbar progress, the OS keychain and system preferences.

Every feature is behind a cargo feature and degrades cleanly: on a platform where it is not implemented (or on the web) a call returns NativeError::Unsupported; nothing panics. The crate never depends on a UI toolkit, so apps wire it to their own event loop: activation events arrive on channels, and callbacks take a waker so an idle app wakes only when something happened.

Module	macOS	Windows	Linux	Web
dialogs	rfd	rfd	rfd (portal)	rfd (bytes only)
menu	muda	muda (per window)	spec only	spec only
clipboard	arboard + NSPasteboard types	arboard	arboard	–
power	NSProcessInfo activity	SetThreadExecutionState	logind inhibit	–
open_files	Apple events + argv	argv	argv	–
single_instance	Unix socket	loopback + token	Unix socket	–
[notify]	UNUserNotificationCenter (bundled apps)	–	D-Bus notifications	–
[progress]	NSDockTile	ITaskbarList3	–	–
[secrets]	Keychain	Credential Manager	Secret Service	–
system	AppKit	registry / SPI	portal settings	media queries
cli_tool	link + admin prompt	–	link (no prompt)	–

modal (always compiled) is a hook around every blocking dialog, for hang watchdogs. terminate (always compiled) runs a hook when the process is asked to stop (SIGINT, SIGTERM, SIGHUP).

unsafe is denied in this crate and allowed only in the FFI modules that need it, each block with a // SAFETY: comment (docs/adr/0001-native-ffi.md).

Modules

cli_tool

Put an app’s bundled command-line tool on the user’s PATH, the way editors offer an “Install command” menu item.

clipboard

The system clipboard: text, RGBA images (arboard) and, on macOS, custom pasteboard types so an app can copy its own data alongside a plain-text fallback.

dialogs

Open, save and folder pickers (rfd).

menu

A native menu bar described by a plain, serializable MenuSpec.

modal

A hook around every call that blocks the calling thread in the OS until the user answers (the native file dialogs and message boxes). A frame-loop hang watchdog pauses itself here: a dialog left open for a minute is not a hung app. Always compiled, so code without the dialogs feature can install the hook too.

open_files

Files and URLs the app is asked to open: from the command line, from the file manager (a double-click on a document of an associated type, a drop on the Dock icon) and from a second launch forwarded by crate::single_instance. They all arrive in one queue, OpenFiles.

power

Keep the system awake, and keep the app at full speed in the background, while long work runs (a render, an export, playback). An RAII guard: the request lasts while the KeepAwake lives.

single_instance

One running instance per user: a second launch forwards its arguments (the files it was asked to open) to the first over a local socket, then exits.

system

System preferences the UI follows (light / dark, accent colour, reduced motion, more contrast) and hand-offs to the OS (open a URL in the browser, open a file in its default app, reveal a file in the file manager).

terminate

Run a hook when the process is asked to stop, then stop as asked. On Unix that is SIGINT (Ctrl-C), SIGTERM and SIGHUP: the first one runs the hook on a thread of its own, after which the signal is delivered again with its default action, so the process ends the way it would have (a shell sees “killed by SIGTERM”). A second signal while the hook runs ends the process at once. For a long-running command-line process (a stdio server) that must write something down before it goes. Always compiled; on other systems on_terminate does nothing.

Enums

NativeError

Why a native call did not do what was asked.

Functions

no_waker

A waker that does nothing, for apps that poll.

Type Aliases

Result

Waker

Something that wakes the app’s event loop (an egui request_repaint, a winit proxy event). Called from background threads after a new event was queued.