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.

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.

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