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:
- 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.
- 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.
- Frozen Windows and Linux builds: confirm the child command opens a native dialog without launching another server and that cancellation closes it.
- Conda desktop: repeat both platform checks through
grime3 web. - Docker, SSH/headless, a non-loopback server, and an unavailable Linux portal: confirm the existing browser opens and no native server-side window appears.
- 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: