# 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`