Sprimo/docs/BEVY_WINDOW_VERIFICATION.md

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

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:

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