Blacksite/docs/editor/native-dialogs.md

Native Dialog Workflows

Blacksite routes native file, folder, Save As, and unsaved-change confirmation dialogs through the shared NativeDialogBroker. A native dialog may remain open without blocking Bevy's window event loop or editor rendering.

Workflow Contract

• One native dialog can be active at a time. Direct controls are disabled while pending; other concurrent requests report that a dialog is already open.
• Native work returns only selected paths or a confirmation result. Scene, asset, project, history, registry, and collaborative-file mutations run later on the Bevy main thread.
• Cancel is non-mutating and produces workflow-specific status.
• Entity-based operations capture the initiating entity and reject stale results. Composition additions validate against the current composition so intervening edits are not overwritten.
• Collaborative Save As performs the same revision and destination checks after selection.
• Close or project switch never treats an opened Save As picker as a completed save. When a save remains pending, the transition pauses and can be retried after saving.
• Native window close, File > Quit, project switch, and programmatic editor exit share the guarded-shutdown coordinator. Dirty scene tabs present exact Save All, Discard, and Cancel actions. Save All remains pending through each untitled tab's Save As result and exits only after every dirty tab is clean; cancellation or failure preserves the live session.
• A close request received while another native dialog owns the broker remains queued. The editor rechecks dirty state and retries acquisition after that workflow completes instead of dropping the request or opening a competing dialog.

Covered Surfaces

The broker owns scene Open/Save As, import/export, prefab creation and relinking, recovery copies, subscene selection, collaborative conflict copies, Project Browser folder selection, and dirty-scene confirmations. New workflows must use the broker instead of calling rfd from an egui/Bevy system.

See ADR 0038. Guarded exit ownership and document savepoints are defined by ADR 0042.

Live native-Wayland acceptance is recorded in the native-dialog responsiveness evaluation.