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`
|
||||
@@ -18,7 +18,7 @@ Date: 2026-02-12
|
||||
| Build/package automation | Implemented (Windows) | `justfile` and `scripts/package_windows.py` generate portable ZIP + SHA256 |
|
||||
| Random backend API tester | Implemented | `scripts/random_backend_tester.py` with `just random-backend-test` and strict variant |
|
||||
| QA/documentation workflow | Implemented | `docs/QA_WORKFLOW.md`, issue/evidence templates, and `scripts/qa_validate.py` with `just qa-validate` |
|
||||
| Shared runtime core | In progress | `sprimo-runtime-core` extracted with shared config/snapshot/API startup and command application |
|
||||
| Shared runtime core | Implemented | `sprimo-runtime-core` now backs both Tauri and Bevy startup, snapshot/config ownership, and API wiring |
|
||||
| Tauri alternative frontend | In progress | `sprimo-tauri` now runs runtime-core/API + PixiJS sprite rendering shell; scale updates now auto-fit window to avoid top clipping |
|
||||
| Tauri runtime testing workflow | Implemented | `docs/TAURI_RUNTIME_TESTING.md` defines strict workspace testing; packaged mode pending packaging support |
|
||||
|
||||
@@ -28,5 +28,4 @@ Date: 2026-02-12
|
||||
2. Linux/macOS overlay behavior remains best-effort with no-op platform adapter.
|
||||
3. `/v1/state` diagnostics are minimal; error history is not persisted beyond latest runtime error.
|
||||
4. Issue 1 runtime after-fix screenshot evidence is still pending before closure.
|
||||
5. `sprimo-app` is not yet refactored to consume `sprimo-runtime-core` directly.
|
||||
6. `sprimo-tauri` still lacks tray/menu/window-behavior parity and full acceptance parity tests.
|
||||
5. `sprimo-tauri` still lacks tray/menu/window-behavior parity and full acceptance parity tests.
|
||||
|
||||
@@ -79,6 +79,9 @@ just random-backend-test
|
||||
```
|
||||
|
||||
For runtime behavior issues, include screenshot capture paths in the issue file.
|
||||
For Bevy window-management verification workflows, use:
|
||||
|
||||
- `docs/BEVY_WINDOW_VERIFICATION.md`
|
||||
|
||||
## Definition of Done
|
||||
|
||||
|
||||
@@ -98,6 +98,7 @@ Legacy issues may reference `issues/screenshots/issueN.png` as before evidence.
|
||||
## Tauri Runtime Behavior Testing
|
||||
|
||||
Authoritative workflow: `docs/TAURI_RUNTIME_TESTING.md`.
|
||||
Bevy window-management verification workflow: `docs/BEVY_WINDOW_VERIFICATION.md`.
|
||||
|
||||
### Workspace Mode (Required Now)
|
||||
|
||||
|
||||
@@ -58,7 +58,5 @@ Frontend:
|
||||
|
||||
## Remaining Work
|
||||
|
||||
1. Move Bevy runtime flow to consume `sprimo-runtime-core` as primary state authority.
|
||||
2. Add tray/menu parity and window behavior parity with Bevy path.
|
||||
3. Extend packaging scripts to include `sprimo-tauri` artifact path.
|
||||
4. Add frontend parity acceptance tests (Bevy vs Tauri state transitions).
|
||||
1. Add tray/menu parity and window behavior parity with Bevy path.
|
||||
2. Add frontend parity acceptance tests (Bevy vs Tauri state transitions).
|
||||
|
||||
Reference in New Issue
Block a user