195 lines
5.1 KiB
Markdown
195 lines
5.1 KiB
Markdown
# 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`
|