This commit is contained in:
1 parent
d038cf3670
commit
ba59f57a5a
11 files changed
+466
-156
No files matched your search
@@ -52,6 +52,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [0035](adr/0035-shared-material-assets-and-renderer-slots.md) | Shared Material/Material Instance assets, stable renderer slots, and runtime-only property blocks |
|
||||
| [0036](adr/0036-surface-abi-and-solari-parity.md) | Constrained Surface ABI v1, raster/Solari evaluator parity, and deformed-geometry boundary |
|
||||
| [0037](adr/0037-collaborative-authored-file-safety.md) | Exact authored-file revisions, observational Git status, and optional ownership providers |
|
||||
| [0038](adr/0038-non-blocking-native-dialog-broker.md) | Worker-owned native waits with one-shot main-thread workflow completion |
|
||||
|
||||
## Editor framework
|
||||
|
||||
@@ -77,6 +78,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [editor/extensibility.md](editor/extensibility.md) | Static authoring component registration, lifecycle, composition, and history contract |
|
||||
| [editor/material-system.md](editor/material-system.md) | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
|
||||
| [editor/collaborative-file-safety.md](editor/collaborative-file-safety.md) | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers |
|
||||
| [editor/native-dialogs.md](editor/native-dialogs.md) | Non-blocking native dialog acquisition and main-thread result application |
|
||||
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
|
||||
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
|
||||
| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
# ADR 0038: Non-Blocking Native Dialog Broker
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Blacksite opens native file, folder, Save As, and confirmation dialogs from editor workflows. Calling
|
||||
the synchronous `rfd` API inside a Bevy/egui system stops window event processing until the dialog
|
||||
returns. On Wayland compositors this can trigger an application-not-responding prompt even though
|
||||
the native dialog is operating normally.
|
||||
|
||||
Path selection precedes stateful main-thread work such as scene serialization, imports, history
|
||||
changes, prefab relinking, collaborative revision checks, and project activation. Moving those
|
||||
operations to arbitrary worker threads would violate ECS ownership and weaken existing guards.
|
||||
|
||||
## Decision
|
||||
|
||||
The editor owns one `NativeDialogBroker` resource. A workflow submits native dialog construction and
|
||||
a typed completion callback. The broker runs only the blocking native dialog wait on a worker thread,
|
||||
then queues the result. An exclusive Bevy system drains the queue and invokes each completion exactly
|
||||
once with `&mut World`.
|
||||
|
||||
Only one native dialog may be active. Additional requests fail immediately with explicit status.
|
||||
Cancellation is delivered as the dialog API's empty or cancel result and remains non-mutating.
|
||||
Initiating workflows capture stable entity IDs or paths and revalidate them before applying a result.
|
||||
|
||||
Native confirmation dialogs use the same broker. A requested close or project switch proceeds only
|
||||
after the confirmation result and any required save have completed; an incomplete asynchronous save
|
||||
pauses the transition rather than discarding content.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Blacksite continues rendering and answering compositor pings while native dialogs are open.
|
||||
- Project and ECS mutations remain on the Bevy main thread with their existing history, validation,
|
||||
and collaborative file-revision boundaries.
|
||||
- Workflows split dialog acquisition from result application and handle stale initiating state.
|
||||
- The one-dialog policy is intentionally global across the editor and Project Browser.
|
||||
- A future platform-specific async backend can replace the worker without changing completions.
|
||||
@@ -24,9 +24,11 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
| [extensibility.md](extensibility.md) | Static authoring component lifecycle registration, stable IDs, composition, and generic history |
|
||||
| [material-system.md](material-system.md) | Shared Material/Material Instance assets, static/skinned renderer slots, Surface ABI, Solari scope, and migration |
|
||||
| [collaborative-file-safety.md](collaborative-file-safety.md) | Exact authored-file revisions, Git/read-only status, conflict recovery, and optional ownership providers |
|
||||
| [native-dialogs.md](native-dialogs.md) | Non-blocking file/folder/confirmation acquisition and main-thread result application |
|
||||
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
|
||||
| [evaluations/material-library-targeted-drop/](evaluations/material-library-targeted-drop/) | Live screenshot and verification record for the docked Material Library and exact reversible surface drops |
|
||||
| [evaluations/collaborative-file-safety/](evaluations/collaborative-file-safety/) | Live screenshot and verification record for source-control status and guarded external-change recovery |
|
||||
| [evaluations/native-dialog-responsiveness/](evaluations/native-dialog-responsiveness/) | Live native-Wayland screenshot and verification record for non-blocking picker responsiveness |
|
||||
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
|
||||
| [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence |
|
||||
|
||||
@@ -48,6 +50,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
| `shared::prefab_overrides` | Versioned stable override schema and editor-independent runtime application | prefab-authoring.md, ADR 0027 |
|
||||
| `project/` | Workspace, settings UI, user prefs, support diagnostics | roadmap Phase 1 |
|
||||
| `project/collaboration.rs` | Guarded authored writes, asynchronous Git status, and optional ownership providers | collaborative-file-safety.md, ADR 0037 |
|
||||
| `project/native_dialog.rs` | One-at-a-time native dialog worker and one-shot main-thread completions | native-dialogs.md, ADR 0038 |
|
||||
| `project/session.rs` | Versioned XDG session document, clean marker, and safe resume | session-recovery.md, ADR 0024 |
|
||||
| `project/diagnostics_bundle.rs` | Privacy-bounded transactional support report export | session-recovery.md, ADR 0024 |
|
||||
| `project/launcher.rs` | Strict project inspection, CLI activation, recent filtering, and sandbox scaffolding | project-launcher.md, ADR 0025 |
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# Native Dialog Responsiveness Evaluation
|
||||
|
||||
Date: 2026-07-12
|
||||
Branch: `codex/non-blocking-native-dialogs`
|
||||
Implementation commits: `d038cf3` and the closing commit for Gitea #52
|
||||
|
||||
This record captures live acceptance for the non-blocking native-dialog broker. The permanent
|
||||
workflow contract lives in the [native-dialog guide](../../native-dialogs.md).
|
||||
|
||||
## Live Editor Evidence
|
||||
|
||||
The native KDE portal Open dialog below was launched through the production `SceneIoRequest::Open`
|
||||
path in a native Wayland debug editor and held open for 12 seconds.
|
||||
|
||||

|
||||
|
||||
During the hold, Hyprland continued to report Blacksite as mapped, visible, input-capable, and native
|
||||
Wayland. No application-not-responding client appeared. Cancel closed the picker without changing the
|
||||
active scene, and the editor then stopped cleanly.
|
||||
|
||||
## Acceptance Results
|
||||
|
||||
| Area | Result | Evidence |
|
||||
|------|--------|----------|
|
||||
| Frame responsiveness | Pass | A blocked-dialog regression test advances eight Bevy frames before releasing the worker; live editor remained compositor-responsive during the 12-second picker hold |
|
||||
| Shared coverage | Pass | Every `rfd::FileDialog` and `rfd::MessageDialog` construction is inside a `NativeDialogBroker::request` worker closure |
|
||||
| Request exclusivity | Pass | Focused test rejects a second request while one is pending and permits work after one-shot completion |
|
||||
| Cancellation | Pass | Live Open cancellation preserved the active scene; workflow callbacks retain explicit non-mutating cancel branches |
|
||||
| Main-thread application | Pass | Paths/results cross the broker, while scene, asset, history, registry, project, and collaboration work remains in `&mut World` completions |
|
||||
| Stale initiating state | Pass | Prefab/export completions reject missing initiating entities; composition validates against current state after selection |
|
||||
| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed here |
|
||||
|
||||
## Automated Verification
|
||||
|
||||
| Command/suite | Result |
|
||||
|---------------|--------|
|
||||
| `cargo fmt --all -- --check` | Pass |
|
||||
| `cargo check --workspace --all-targets` | Pass |
|
||||
| `cargo clippy --workspace --all-targets -- -D warnings` | Pass |
|
||||
| `cargo test --workspace` | Pass |
|
||||
| Focused native-dialog lifecycle and frame-progress tests | 2 passed |
|
||||
| `git diff --check` | Pass |
|
||||
Binary file not shown.
@@ -0,0 +1,29 @@
|
||||
# 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/).
|
||||
Reference in new issue
Block a user