# 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](../adr/0038-non-blocking-native-dialog-broker.md).

Live native-Wayland acceptance is recorded in the
[native-dialog responsiveness evaluation](evaluations/native-dialog-responsiveness/).