Add: logical verification workflow for bevy
This commit is contained in:
DaZuo0122
194
docs/BEVY_WINDOW_VERIFICATION.md
Normal file
194
docs/BEVY_WINDOW_VERIFICATION.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# Bevy Window Management Verification (Windows-First)
|
||||
|
||||
Date: 2026-02-13
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines a logical verification workflow for `sprimo-app` window management.
|
||||
It combines code-path assertions with lightweight runtime validation.
|
||||
|
||||
Primary focus:
|
||||
|
||||
- window visibility behavior
|
||||
- always-on-top behavior
|
||||
- position and scale handling
|
||||
- recovery hotkey behavior
|
||||
- snapshot/config consistency
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- `crates/sprimo-app/src/main.rs`
|
||||
- `crates/sprimo-platform/src/lib.rs`
|
||||
- window-related runtime-core integration path in `sprimo-app`
|
||||
- API commands: `SetTransform`, `SetFlags`
|
||||
|
||||
Out of scope:
|
||||
|
||||
- tray/menu behavior
|
||||
- tauri frontend window behavior
|
||||
- long soak/performance testing
|
||||
|
||||
## Requirements Traceability
|
||||
|
||||
| Requirement | Intent | Code path(s) |
|
||||
|---|---|---|
|
||||
| FR-FW-1 | Borderless/transparent overlay | `crates/sprimo-app/src/main.rs` window setup (`decorations=false`, clear color/transparent mode) |
|
||||
| FR-FW-2 | Always-on-top toggle | `crates/sprimo-app/src/main.rs` (`SetFlags.always_on_top`), `crates/sprimo-platform/src/lib.rs` (`set_always_on_top`) |
|
||||
| FR-FW-3 | Recovery to visible/interactive | `crates/sprimo-app/src/main.rs` (`poll_hotkey_recovery`) |
|
||||
| FR-FW-4 | Positioning persistence + move | `crates/sprimo-app/src/main.rs` (`SetTransform x/y`, startup position), runtime-core config persistence |
|
||||
| FR-FW-5 | Position handling under monitor/DPI context | logical verification of position updates via platform adapter + snapshot/config |
|
||||
|
||||
## Code-Path Logical Checklist
|
||||
|
||||
1. Startup invariants:
|
||||
- window is undecorated and non-resizable
|
||||
- startup position uses persisted `window.x` / `window.y`
|
||||
- startup top-most intent is configured
|
||||
|
||||
2. Handle-attach invariants:
|
||||
- `attach_window_handle_once` applies at most once
|
||||
- on Windows, native handle attach occurs before platform calls
|
||||
- initial snapshot values are applied to platform (`always_on_top`, `visible`, `position`)
|
||||
|
||||
3. Command invariants:
|
||||
- `SetTransform.scale` updates sprite scale and window size (`window_size_for_pack`)
|
||||
- `SetTransform.x/y` updates logical position state and issues platform move
|
||||
- `SetFlags.always_on_top` triggers platform top-most call
|
||||
- `SetFlags.visible` triggers platform visibility call and Bevy `Visibility`
|
||||
|
||||
4. Recovery invariants:
|
||||
- hotkey path enforces `visible=true` and `always_on_top=true`
|
||||
- recovery updates logical state via runtime-core command path
|
||||
|
||||
5. Persistence/snapshot invariants:
|
||||
- window fields (`x`, `y`, `scale`, `flags`) roundtrip through runtime-core
|
||||
- `/v1/state` stays consistent with command outcomes
|
||||
|
||||
6. Degradation invariants (non-Windows):
|
||||
- no-op adapter does not crash on window commands
|
||||
- capability semantics remain conservative
|
||||
|
||||
## Lightweight Runtime Checklist (Windows)
|
||||
|
||||
Preconditions:
|
||||
|
||||
- run `sprimo-app`
|
||||
- resolve token/port from `%APPDATA%/sprimo/config/config.toml`
|
||||
|
||||
### Scenario 1: Baseline
|
||||
|
||||
1. `GET /v1/health`
|
||||
2. `GET /v1/state` with bearer token
|
||||
3. Record `x`, `y`, `scale`, `flags.visible`, `flags.always_on_top`
|
||||
|
||||
Expected:
|
||||
|
||||
- health endpoint alive
|
||||
- state endpoint authorized
|
||||
- window fields present and coherent
|
||||
|
||||
### Scenario 2: Position Command
|
||||
|
||||
1. Send `SetTransform` with `x` and `y`.
|
||||
2. Re-check `/v1/state`.
|
||||
|
||||
Expected:
|
||||
|
||||
- `x`/`y` update in snapshot
|
||||
- window visibly moves
|
||||
|
||||
### Scenario 3: Scale Command
|
||||
|
||||
1. Send `SetTransform` with `scale`.
|
||||
2. Re-check `/v1/state`.
|
||||
|
||||
Expected:
|
||||
|
||||
- `scale` updates
|
||||
- window dimensions update according to frame size + padding
|
||||
|
||||
### Scenario 4: Visibility Toggle
|
||||
|
||||
1. Send `SetFlags { visible: false }`.
|
||||
2. Send `SetFlags { visible: true }`.
|
||||
3. Re-check `/v1/state`.
|
||||
|
||||
Expected:
|
||||
|
||||
- visible flag transitions correctly
|
||||
- window hides/shows without crash
|
||||
|
||||
### Scenario 5: Always-On-Top Toggle
|
||||
|
||||
1. Send `SetFlags { always_on_top: false }`.
|
||||
2. Send `SetFlags { always_on_top: true }`.
|
||||
3. Re-check `/v1/state`.
|
||||
|
||||
Expected:
|
||||
|
||||
- top-most flag transitions correctly
|
||||
- OS behavior matches expected z-order changes
|
||||
|
||||
### Scenario 6: Recovery Hotkey
|
||||
|
||||
1. Move to non-ideal state (hidden and/or not top-most).
|
||||
2. Trigger configured recovery hotkey (default `Ctrl+Alt+P`).
|
||||
3. Re-check `/v1/state`.
|
||||
|
||||
Expected:
|
||||
|
||||
- forces `visible=true`
|
||||
- forces `always_on_top=true`
|
||||
|
||||
### Scenario 7: Restart Persistence
|
||||
|
||||
1. Restart `sprimo-app`.
|
||||
2. Re-check `/v1/state`.
|
||||
|
||||
Expected:
|
||||
|
||||
- `x`, `y`, `scale`, `always_on_top`, `visible` persist
|
||||
|
||||
## Suggested Command Set
|
||||
|
||||
```powershell
|
||||
cargo check -p sprimo-app
|
||||
cargo check -p sprimo-platform
|
||||
cargo check -p sprimo-runtime-core
|
||||
cargo test -p sprimo-app
|
||||
cargo test -p sprimo-runtime-core
|
||||
just qa-validate
|
||||
```
|
||||
|
||||
Optional runtime stress after directed checks:
|
||||
|
||||
```powershell
|
||||
just random-backend-test
|
||||
```
|
||||
|
||||
## Pass / Fail Criteria
|
||||
|
||||
Pass:
|
||||
|
||||
- all logical assertions hold
|
||||
- runtime scenarios behave as expected
|
||||
- `/v1/state` remains consistent with visible behavior
|
||||
- no crashes/panics in window-command paths
|
||||
|
||||
Fail:
|
||||
|
||||
- mismatch between command outcome and snapshot
|
||||
- recovery hotkey fails to restore visible top-most state
|
||||
- restart persistence for window fields fails
|
||||
- any crash in window-management flow
|
||||
|
||||
## Evidence Expectations
|
||||
|
||||
For issue-driven verification, attach:
|
||||
|
||||
- command summary
|
||||
- before/after screenshots
|
||||
- `/v1/state` snapshots before and after key transitions
|
||||
- lifecycle updates in `issues/issueN.md` per `docs/QA_WORKFLOW.md`
|
||||
Reference in New Issue
Block a user