Native file and folder browsing

On a local desktop, start grime3 web --host 127.0.0.1 --open-browser and use the exact browser URL printed by the launcher. The same public command works in Conda; the desktop packages invoke the same launcher.

Browse now selects image folders, measurement output folders, existing Data Root folders, Site package folders, and Site Configuration JSON files. Create and Save As select a JSON destination. Image folders and configurations load after selection; output, Data Root, and Site package selections fill their path fields without starting a run or registering a root. Native folder selection requires an existing directory. Manual output paths can still name a new directory for the normal output service to create. Manual path entry and Enter-to-load remain supported.

Windows uses the shell IFileOpenDialog for files/folders and IFileSaveDialog for JSON destinations. Linux uses org.freedesktop.portal.FileChooser, version 3 or later, through the installed GIO/GLib libraries. It needs a local graphical session, its session D-Bus, the desktop portal, and a FileChooser backend. The Legion inspection found version 3 with the GTK backend on XFCE/X11. No Qt, Tk, gi, dbus, or dbus_next dependency is added to GRIME3.

Cancel leaves the path unchanged and does not load, create, or save anything. Only one native picker may be active per server process, including across browser tabs. The browser disables measurement controls while selection is pending. Native dialogs are independent windows because GRIME3 does not own the web browser's window handle; check the taskbar if one appears behind it.

The dialog runs in a child process with its own Windows STA or Linux GLib context. Interaction is bounded to four minutes, with a short allowance for worker startup/cleanup. Linux explicitly closes a portal request on timeout; worker timeout terminates the child. Cancellation is distinct from provider failure. An unavailable provider, malformed/nonlocal URI, invalid selection, or worker failure opens the existing GRIME3 browser instead. JSON filters aid selection, and the backend still requires a .json path. Only filesystem paths accessible to the backend are returned.

Choosing a save destination does not write the configuration. Windows disables its test-file creation behavior; existing GRIME3 Create/Save validation and overwrite confirmation remain authoritative. The system save picker may also ask before replacing an existing file. Cancelling either confirmation leaves the existing file untouched.

Local access and fallback

Native browsing is enabled only by the production launcher when binding 127.0.0.1, localhost, or ::1. The browser must use that launcher's exact origin and port. Native endpoints require a loopback peer, the expected Host, matching Origin for selection, and the token issued by that server process. Forwarded/proxy and cross-site requests are refused. Uvicorn does not rewrite peer addresses from proxy headers. Tokens are memory-only, are not persisted in browser storage, and capability/selection responses use Cache-Control: no-store. These guards apply to native selection; they do not add general remote authentication to the existing GRIME3 APIs.

The default create_app() has no native desktop authority. Direct ASGI hosting, non-loopback bindings, Docker/containers, SSH, headless sessions, unsupported platforms, unavailable GIO/portal services, and Windows noninteractive/remote desktops retain the existing GRIME3 browser. No services are started by Linux capability probing. Manual entry and browser browsing remain available.

GET /api/native-picker/capability reports availability, provider, supported kinds, reason, and a session token only for an eligible local browser. POST /api/native-picker/select accepts kind (folder, open_json, or save_json), initial_path, title, and token. The response status is selected, cancelled, busy, or fallback; only selected contains a path. The private _native-picker-worker command is a stdin/stdout JSON protocol used by the server, not a user workflow. Source/Conda workers use Python's module entry point; frozen workers re-enter the same executable with that private command.

Validation gates

Automated tests cover local-origin/token restrictions, remote/proxy requests, strict request fields, single-dialog exclusion, worker errors/timeouts, paths with spaces and Spanish characters, save without file creation, Windows COM provider call/cleanup contracts, real GLib variant marshalling, and browser selection/cancellation/fallback/overwrite flows under Node or JavaScriptCore. Linux transport tests start a private D-Bus and simulated portal, never a GUI; they cover capability version, early Response signals, native URI decoding, cancellation, invalid results, and timeout/Close. They skip when system GIO or D-Bus is unavailable or the execution environment forbids private sockets.

Before releasing RC9, validate these on real local desktops and built packages:

  1. Linux XFCE/X11 and, when available, Wayland: Browse each folder control, load JSON, create a new configuration, Save As, and cancel each kind. Check that selecting a Data Root does not register it automatically.
  2. Native Windows, without WSL: repeat folder/open/save/cancel, use Spanish and spaced paths, cancel overwrite, and try two tabs. Confirm only one picker opens.
  3. Frozen Windows and Linux builds: confirm the child command opens a native dialog without launching another server and that cancellation closes it.
  4. Conda desktop: repeat both platform checks through grime3 web.
  5. Docker, SSH/headless, a non-loopback server, and an unavailable Linux portal: confirm the existing browser opens and no native server-side window appears.
  6. Close a picker, start another, and exercise normal measurement to confirm server lifecycle, scientific results, quality evidence, and CSV behavior.

Linux XFCE/X11 browser smoke checks passed for image/output/Data Root/Site folder selection, JSON loading, Save As cancellation, and repeated dialog use. Folder selection does not register a Data Root or Site automatically. Full Create/save/overwrite interaction checks, native Windows desktop checks, and frozen-package validation remain release gates; provider contracts do not substitute for those checks.

Platform API references: