Blacksite/.cursor/plans/non_blocking_native_dialogs_2026-07-12.plan.md

Non-Blocking Native Dialogs

Historical plan — not current implementation guidance. Use the documentation index for current behavior and architecture.

Working implementation plan for the production-readiness defect discovered during live acceptance of collaborative file safety. Opening an rfd picker synchronously from an egui/Bevy system stops window event processing long enough for Hyprland to report Blacksite as unresponsive.

Scope

1. Add one project-level native-dialog broker with a typed intent, one active dialog, background native work, and a main-thread result queue.
2. Convert scene open/save-as, asset import/export, prefab save/source selection, subscene selection, conflict Save As, diagnostics export, and project-launcher folder selection to the broker.
3. Keep destructive or stateful application logic on the Bevy main thread after a path result is received. Background work may only own the native dialog and its returned paths.
4. Show a stable pending state and reject duplicate dialog requests while a picker is active.
5. Replace blocking native dirty-scene confirmation dialogs with an editor-owned modal when the scene-transition state machine can preserve the original action exactly.

Contract

• The editor continues rendering and processing compositor pings while a native dialog is open.
• Cancel returns a typed empty result and does not mutate editor state.
• A result is applied once to the intent that created it; stale or duplicate results cannot run.
• Paths are validated at the same ownership boundary as before. The dialog broker does not read, write, import, save, or canonicalize project content.
• Existing collaborative revision guards remain authoritative after Save As selection.
• Project-launcher dialogs use the same broker before the full editor plugin group is active.

Verification

• Focused tests cover request exclusivity, cancel, one-shot result delivery, and typed intent preservation.
• Source-only workspace formatting, check, strict Clippy, and tests run; packaged acceptance remains deferred by project-owner direction.
• Native Wayland QA opens representative file, folder, and Save As dialogs under Hyprland and confirms the Blacksite window remains responsive without an unresponsive-application prompt.