manbo/Sprimo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Add: logical verification workflow for bevy

Browse Source
This commit is contained in:
DaZuo0122
2026-02-13 21:54:30 +08:00
parent 8e79bd98e5
commit 875bc54c4f
8 changed files with 266 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Cargo.lock generated
View File

@@ -6039,6 +6039,7 @@ dependencies = [
"sprimo-config",
"sprimo-platform",
"sprimo-protocol",
"sprimo-runtime-core",
"sprimo-sprite",
"thiserror 2.0.18",
"tokio",

1
crates/sprimo-app/Cargo.toml
View File

@@ -15,6 +15,7 @@ sprimo-api = { path = "../sprimo-api" }
sprimo-config = { path = "../sprimo-config" }
sprimo-platform = { path = "../sprimo-platform" }
sprimo-protocol = { path = "../sprimo-protocol" }
sprimo-runtime-core = { path = "../sprimo-runtime-core" }
sprimo-sprite = { path = "../sprimo-sprite" }
thiserror.workspace = true
tokio.workspace = true

176
crates/sprimo-app/src/main.rs
View File

@@ -6,10 +6,9 @@ use bevy::render::render_resource::{Extent3d, TextureDimension, TextureFormat};
use bevy::window::{PrimaryWindow, WindowLevel, WindowMode, WindowPlugin, WindowPosition};
use image::{DynamicImage, GenericImageView, Rgba};
use raw_window_handle::{HasWindowHandle, RawWindowHandle};
use sprimo_api::{ApiConfig, ApiState};
use sprimo_config::{save, AppConfig, ConfigError};
use sprimo_platform::{create_adapter, PlatformAdapter};
use sprimo_protocol::v1::{CommandEnvelope, FrontendCommand, FrontendState, FrontendStateSnapshot};
use sprimo_runtime_core::{RuntimeCore, RuntimeCoreError};
use sprimo_sprite::{
load_manifest, resolve_pack_path, AnimationDefinition, SpriteError, SpritePackManifest,
};
@@ -20,8 +19,7 @@ use std::sync::{Arc, RwLock};
use std::time::Duration;
use thiserror::Error;
use tokio::runtime::Runtime;
use tokio::sync::mpsc as tokio_mpsc;
use tracing::{error, info, warn};
use tracing::{info, warn};
const APP_NAME: &str = "sprimo";
const DEFAULT_PACK: &str = "default";
@@ -35,7 +33,7 @@ const WINDOWS_COLOR_KEY: [u8; 3] = [255, 0, 255];
#[derive(Debug, Error)]
enum AppError {
#[error("{0}")]
Config(#[from] ConfigError),
RuntimeCore(#[from] RuntimeCoreError),
}
#[derive(Resource, Clone)]
@@ -45,10 +43,7 @@ struct SharedSnapshot(Arc<RwLock<FrontendStateSnapshot>>);
struct PlatformResource(Arc<dyn PlatformAdapter>);
#[derive(Resource)]
struct ConfigResource {
path: PathBuf,
config: AppConfig,
}
struct RuntimeCoreResource(Arc<RuntimeCore>);
#[derive(Resource, Copy, Clone)]
struct DurableState {
@@ -181,35 +176,30 @@ fn main() -> Result<(), AppError> {
.compact()
.init();
let (config_path, mut config) = sprimo_config::load_or_create(APP_NAME)?;
if config.window.click_through {
config.window.click_through = false;
if let Err(err) = save(&config_path, &config) {
warn!(%err, "failed to persist click-through disable at startup");
}
}
let platform: Arc<dyn PlatformAdapter> = create_adapter().into();
let capabilities = platform.capabilities();
let mut snapshot = FrontendStateSnapshot::idle(capabilities);
snapshot.x = config.window.x;
snapshot.y = config.window.y;
snapshot.scale = config.window.scale;
snapshot.flags.click_through = false;
snapshot.flags.always_on_top = config.window.always_on_top;
snapshot.flags.visible = config.window.visible;
snapshot.active_sprite_pack = config.sprite.selected_pack.clone();
let shared_snapshot = Arc::new(RwLock::new(snapshot));
let runtime_core = Arc::new(RuntimeCore::new(APP_NAME, platform.capabilities())?);
let shared_snapshot = runtime_core.snapshot();
let config = runtime_core
.config()
.read()
.expect("runtime core config lock poisoned")
.clone();
let runtime = Runtime::new().expect("tokio runtime");
let (api_command_tx, api_command_rx) = tokio_mpsc::channel(1_024);
let (bevy_command_tx, bevy_command_rx) = mpsc::channel();
let (hotkey_tx, hotkey_rx) = mpsc::channel();
spawn_api(&runtime, &config, Arc::clone(&shared_snapshot), api_command_tx);
runtime_core.spawn_api(&runtime);
let command_rx = runtime_core.command_receiver();
runtime.spawn(async move {
let mut rx = api_command_rx;
while let Some(command) = rx.recv().await {
loop {
let next = {
let mut receiver = command_rx.lock().await;
receiver.recv().await
};
let Some(command) = next else {
break;
};
if bevy_command_tx.send(command).is_err() {
break;
}
@@ -245,11 +235,8 @@ fn main() -> Result<(), AppError> {
app.insert_resource(ClearColor(window_clear_color()));
app.insert_resource(SharedSnapshot(shared_snapshot));
app.insert_resource(RuntimeCoreResource(Arc::clone(&runtime_core)));
app.insert_resource(PlatformResource(Arc::clone(&platform)));
app.insert_resource(ConfigResource {
path: config_path,
config,
});
app.insert_resource(DurableState {
state: FrontendState::Idle,
});
@@ -281,23 +268,6 @@ fn main() -> Result<(), AppError> {
Ok(())
}
fn spawn_api(
runtime: &Runtime,
config: &AppConfig,
shared_snapshot: Arc<RwLock<FrontendStateSnapshot>>,
api_command_tx: tokio_mpsc::Sender<CommandEnvelope>,
) {
let mut api_config = ApiConfig::default_with_token(config.api.auth_token.clone());
api_config.bind_addr = ([127, 0, 0, 1], config.api.port).into();
let api_state = Arc::new(ApiState::new(api_config.clone(), shared_snapshot, api_command_tx));
runtime.spawn(async move {
if let Err(err) = sprimo_api::run_server(api_config, api_state).await {
error!(%err, "api server exited");
}
});
}
fn default_asset_root() -> PathBuf {
std::env::current_dir()
.unwrap_or_else(|_| PathBuf::from("."))
@@ -307,7 +277,7 @@ fn default_asset_root() -> PathBuf {
fn setup_scene(
mut commands: Commands,
config: Res<ConfigResource>,
runtime_core: Res<RuntimeCoreResource>,
root: Res<SpritePackRoot>,
mut texture_layouts: ResMut<Assets<TextureAtlasLayout>>,
mut images: ResMut<Assets<Image>>,
@@ -323,7 +293,14 @@ fn setup_scene(
..default()
});
let selected = config.config.sprite.selected_pack.clone();
let selected = runtime_core
.0
.config()
.read()
.expect("runtime core config lock poisoned")
.sprite
.selected_pack
.clone();
let runtime = match load_pack_runtime(
&root.asset_root,
&selected,
@@ -749,8 +726,7 @@ fn attach_window_handle_once(
fn poll_hotkey_recovery(
ingress: NonSendMut<HotkeyIngress>,
platform: Res<PlatformResource>,
mut config: ResMut<ConfigResource>,
snapshot: Res<SharedSnapshot>,
runtime_core: Res<RuntimeCoreResource>,
mut pet_query: Query<&mut Visibility, With<PetSprite>>,
) {
while ingress.0.try_recv().is_ok() {
@@ -761,18 +737,12 @@ fn poll_hotkey_recovery(
if let Ok(mut visibility) = pet_query.get_single_mut() {
*visibility = Visibility::Visible;
}
config.config.window.always_on_top = true;
config.config.window.visible = true;
if let Err(err) = save(&config.path, &config.config) {
warn!(%err, "failed to persist config after hotkey recovery");
}
if let Ok(mut guard) = snapshot.0.write() {
guard.flags.click_through = false;
guard.flags.always_on_top = true;
guard.flags.visible = true;
guard.last_error = None;
if let Err(err) = runtime_core.0.apply_command(&FrontendCommand::SetFlags {
click_through: None,
always_on_top: Some(true),
visible: Some(true),
}) {
warn!(%err, "failed to persist recovery flag config");
}
}
}
@@ -784,7 +754,7 @@ fn poll_backend_commands(
asset_server: Res<AssetServer>,
mut images: ResMut<Assets<Image>>,
mut texture_layouts: ResMut<Assets<TextureAtlasLayout>>,
mut config: ResMut<ConfigResource>,
runtime_core: Res<RuntimeCoreResource>,
snapshot: Res<SharedSnapshot>,
mut durable_state: ResMut<DurableState>,
mut reset: ResMut<PendingStateReset>,
@@ -800,6 +770,7 @@ fn poll_backend_commands(
let Ok(envelope) = ingress.0.try_recv() else {
break;
};
let command = envelope.command;
let Ok((mut transform, mut visibility, mut atlas, mut image_handle)) =
pet_query.get_single_mut()
@@ -807,7 +778,14 @@ fn poll_backend_commands(
continue;
};
match envelope.command {
if !matches!(command, FrontendCommand::SetSpritePack { .. }) {
if let Err(err) = runtime_core.0.apply_command(&command) {
warn!(%err, "failed to apply command in runtime core");
continue;
}
}
match command {
FrontendCommand::SetState { state, ttl_ms } => {
if !matches!(state, FrontendState::Success | FrontendState::Error) {
durable_state.state = state;
@@ -878,8 +856,11 @@ fn poll_backend_commands(
window.resolution.set(size.x, size.y);
}
config.config.sprite.selected_pack = requested;
if let Err(err) = save(&config.path, &config.config) {
if let Err(err) = runtime_core.0.apply_command(
&FrontendCommand::SetSpritePack {
pack_id_or_path: requested.clone(),
},
) {
warn!(%err, "failed to persist sprite pack selection");
}
@@ -899,37 +880,17 @@ fn poll_backend_commands(
}
}
FrontendCommand::SetTransform { x, y, scale, .. } => {
if let Some(value) = x {
config.config.window.x = value;
}
if let Some(value) = y {
config.config.window.y = value;
}
if let Some(value) = scale {
transform.scale = Vec3::splat(value);
config.config.window.scale = value;
if let Ok(mut window) = window_query.get_single_mut() {
let size = window_size_for_pack(&current_pack.runtime, value);
window.resolution.set(size.x, size.y);
}
}
let _ = platform
.0
.set_window_position(config.config.window.x, config.config.window.y);
if let Err(err) = save(&config.path, &config.config) {
warn!(%err, "failed to persist transform config");
if x.is_some() || y.is_some() {
if let Ok(guard) = snapshot.0.read() {
let _ = platform.0.set_window_position(guard.x, guard.y);
}
if let Ok(mut guard) = snapshot.0.write() {
if let Some(value) = x {
guard.x = value;
}
if let Some(value) = y {
guard.y = value;
}
if let Some(value) = scale {
guard.scale = value;
}
guard.last_error = None;
}
}
FrontendCommand::SetFlags {
@@ -937,36 +898,18 @@ fn poll_backend_commands(
always_on_top,
visible,
} => {
if click_through.is_some() {
config.config.window.click_through = false;
}
let _ = click_through;
if let Some(value) = always_on_top {
let _ = platform.0.set_always_on_top(value);
config.config.window.always_on_top = value;
}
if let Some(value) = visible {
let _ = platform.0.set_visible(value);
config.config.window.visible = value;
*visibility = if value {
Visibility::Visible
} else {
Visibility::Hidden
};
}
if let Err(err) = save(&config.path, &config.config) {
warn!(%err, "failed to persist flag config");
}
if let Ok(mut guard) = snapshot.0.write() {
guard.flags.click_through = false;
if let Some(value) = always_on_top {
guard.flags.always_on_top = value;
}
if let Some(value) = visible {
guard.flags.visible = value;
}
guard.last_error = None;
}
}
FrontendCommand::Toast { text, .. } => {
info!(toast = text, "toast command received");
@@ -977,6 +920,7 @@ fn poll_backend_commands(
fn tick_state_reset(
time: Res<Time>,
runtime_core: Res<RuntimeCoreResource>,
mut reset: ResMut<PendingStateReset>,
mut animation: ResMut<AnimationResource>,
current_pack: Res<CurrentPackResource>,
@@ -993,6 +937,10 @@ fn tick_state_reset(
let next_state = reset.revert_to;
let next_animation = default_animation_for_state(next_state);
let _ = runtime_core.0.apply_command(&FrontendCommand::SetState {
state: next_state,
ttl_ms: None,
});
set_animation(&mut animation, &current_pack.runtime.clips, next_animation);
if let Ok(mut atlas) = atlas_query.get_single_mut() {
if let Some(frame) = current_frame(&animation, &current_pack.runtime.clips) {

194
docs/BEVY_WINDOW_VERIFICATION.md Normal file
View 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`

5
docs/IMPLEMENTATION_STATUS.md
View File

@@ -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.

3
docs/QA_WORKFLOW.md
View File

@@ -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

1
docs/RELEASE_TESTING.md
View File

@@ -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)

6
docs/TAURI_FRONTEND_DESIGN.md
View File

@@ -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).