# 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](../adr/0038-non-blocking-native-dialog-broker.md).
Guarded exit ownership and document savepoints are defined by
[ADR 0042](../adr/0042-guarded-editor-shutdown-and-document-savepoints.md).

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