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

Add: tauri frontend as bevy alternative

Browse Source
This commit is contained in:
DaZuo0122
2026-02-13 09:57:08 +08:00
parent b0f462f63e
commit 3c3ca342c9
33 changed files with 11798 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/ARCHITECTURE.md
View File

@@ -3,20 +3,22 @@
## Workspace Layout
- `crates/sprimo-app`: process entrypoint and runtime wiring.
- `crates/sprimo-tauri`: Tauri 2.0 alternative frontend entrypoint.
- `crates/sprimo-api`: axum-based localhost control server.
- `crates/sprimo-config`: config schema, path resolution, persistence.
- `crates/sprimo-platform`: platform abstraction for overlay operations.
- `crates/sprimo-protocol`: shared API/state/command protocol types.
- `crates/sprimo-runtime-core`: shared runtime core for command/state/API orchestration.
- `crates/sprimo-sprite`: sprite pack manifest loading and fallback logic.
## Runtime Data Flow
1. `sprimo-app` loads or creates `config.toml`.
2. App builds initial `FrontendStateSnapshot`.
3. App starts `sprimo-api` on a Tokio runtime.
1. Frontend (`sprimo-app` or `sprimo-tauri`) initializes `sprimo-runtime-core`.
2. Runtime core loads/creates `config.toml` and builds initial `FrontendStateSnapshot`.
3. Runtime core starts `sprimo-api` on a Tokio runtime.
4. API authenticates commands and deduplicates IDs.
5. Commands are bridged from Tokio channel to Bevy main-thread systems.
6. Bevy systems apply commands to sprite state, window/platform operations, and config persistence.
5. Commands are bridged from API channel into frontend-specific command handlers.
6. Frontend adapter applies rendering/window effects and runtime core applies snapshot/config state.
7. Shared snapshot is exposed by API via `/v1/state` and `/v1/health`.
## Sprite Reload Semantics
@@ -32,6 +34,7 @@
- API task: axum server.
- Bridge task: forwards API commands into Bevy ingest channel.
- Bevy main thread: rendering, animation, command application, and window behavior.
- Tauri thread/runtime: webview UI, event loop, and runtime command consumer.
- Optional hotkey thread (Windows): registers global hotkey and pushes recovery events.
- Snapshot is shared via `Arc<RwLock<_>>`.

4
docs/CONFIG_REFERENCE.md
View File

@@ -36,6 +36,9 @@ level = "info"
[controls]
hotkey_enabled = true
recovery_hotkey = "Ctrl+Alt+P"
[frontend]
backend = "bevy"
```
## Notes
@@ -43,3 +46,4 @@ recovery_hotkey = "Ctrl+Alt+P"
- `auth_token` is generated on first run if config does not exist.
- `window.x`, `window.y`, `window.scale`, and flag fields are persisted after matching commands.
- On Windows, `recovery_hotkey` provides click-through recovery even when the window is non-interactive.
- `frontend.backend` selects runtime frontend implementation (`bevy` or `tauri`).

5
docs/IMPLEMENTATION_STATUS.md
View File

@@ -17,6 +17,9 @@ Date: 2026-02-12
| Embedded default pack | Implemented | Bundled under `assets/sprite-packs/default/` using `sprite.png` (8x7, 512x512 frames) |
| Build/package automation | Implemented (Windows) | `justfile` and `scripts/package_windows.py` generate portable ZIP + SHA256 |
| 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 |
| Tauri alternative frontend | In progress | `sprimo-tauri` now runs runtime-core/API + PixiJS sprite rendering shell, parity work remains |
| Tauri runtime testing workflow | Implemented | `docs/TAURI_RUNTIME_TESTING.md` defines strict workspace testing; packaged mode pending packaging support |
## Next Major Gaps
@@ -24,3 +27,5 @@ 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.

11
docs/QA_WORKFLOW.md
View File

@@ -83,3 +83,14 @@ An issue is done only when:
- evidence links resolve to files in repository
- `just qa-validate` passes
## Tauri Runtime Addendum
For `sprimo-tauri` runtime behavior issues, follow `docs/TAURI_RUNTIME_TESTING.md`.
Additional strict requirements:
- include `current_state` and `load_active_sprite_pack` invoke validation notes
- include `runtime:snapshot` event verification notes
- include tauri runtime API verification (`/v1/health`, `/v1/state`, `/v1/command`, `/v1/commands`)
- do not move issue status to `Closed` until all strict-gate evidence in
`docs/TAURI_RUNTIME_TESTING.md` is present

28
docs/RELEASE_TESTING.md
View File

@@ -70,3 +70,31 @@ Before release sign-off for a bug fix:
- `just qa-validate`
Legacy issues may reference `issues/screenshots/issueN.png` as before evidence.
## Tauri Runtime Behavior Testing
Authoritative workflow: `docs/TAURI_RUNTIME_TESTING.md`.
### Workspace Mode (Required Now)
1. `just build-tauri-ui`
2. `just check-tauri`
3. `just check-runtime-core`
4. `just run-tauri` (smoke and runtime observation)
5. Verify invoke/event contract behavior:
- `current_state`
- `load_active_sprite_pack`
- `runtime:snapshot`
6. Verify API/runtime contract behavior against tauri process:
- `/v1/health`
- `/v1/state` with auth
- `/v1/command`
- `/v1/commands`
### Packaged Mode (Required Once Tauri Packaging Exists)
When tauri packaging automation is available, repeat runtime behavior checks on packaged artifacts:
1. Launch packaged tauri app.
2. Re-run invoke/event/API checks from workspace mode.
3. Attach before/after screenshots and command summaries in linked issue.

61
docs/TAURI_FRONTEND_DESIGN.md Normal file
View File

@@ -0,0 +1,61 @@
# Tauri 2.0 Frontend Design (Bevy Alternative)
Date: 2026-02-12
## Goal
Add a Tauri 2.0 frontend path as an alternative to Bevy while keeping the existing Bevy
implementation and API behavior.
## New Components
- `crates/sprimo-runtime-core`
- shared runtime bootstrap for config/snapshot/API/channel setup
- shared command-to-snapshot/config application
- `crates/sprimo-tauri`
- Tauri 2.0 desktop shell
- command consumer loop bound to runtime core
- invoke command `current_state` for UI state
- `frontend/tauri-ui`
- React + Vite UI shell for status/control surface
## Selected Crates
Rust:
- `tauri`
- `tauri-build`
- `tauri-plugin-log`
- `tauri-plugin-global-shortcut`
- existing internal crates:
- `sprimo-runtime-core`
- `sprimo-platform`
- `sprimo-protocol`
Frontend:
- `react`
- `react-dom`
- `vite`
- `typescript`
- `@tauri-apps/api`
## Current State
- Tauri binary crate is scaffolded and starts runtime core + API server.
- Runtime core receives API commands and updates shared snapshot/config state.
- Tauri backend exposes:
- `current_state` command (structured snapshot DTO)
- `load_active_sprite_pack` command (manifest + atlas as base64 data URL)
- `runtime:snapshot` event after command application.
- React/Vite frontend now renders sprite atlas frames with PixiJS and updates animation/scale
from runtime snapshot events.
- Bevy frontend remains intact.
- Runtime QA workflow is defined in `docs/TAURI_RUNTIME_TESTING.md`.
## 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).

131
docs/TAURI_RUNTIME_TESTING.md Normal file
View File

@@ -0,0 +1,131 @@
# Tauri Runtime Behavior Testing Workflow
Date: 2026-02-13
## Purpose and Scope
This document defines strict testing and evidence requirements for `sprimo-tauri` runtime
behaviors. It complements `docs/QA_WORKFLOW.md` and applies to all Tauri runtime behavior issues.
## Prerequisites
- Windows environment for primary runtime validation.
- Workspace up to date.
- UI dependencies installed:
- `just install-tauri-ui`
## Execution Modes
### 1. Workspace Mode (Required Now)
Run and validate from the repository workspace:
```powershell
just build-tauri-ui
just check-tauri
just check-runtime-core
just run-tauri
```
### 2. Packaged Mode (Required Once Packaging Exists)
When `sprimo-tauri` packaging automation is implemented, repeat the runtime checklist against the
packaged artifact and attach equivalent evidence in the issue.
## Strict Verification Gate
An issue touching Tauri runtime behaviors must satisfy all requirements before `Closed`:
1. Command evidence recorded:
- `cargo check -p sprimo-tauri`
- `cargo check -p sprimo-runtime-core`
- `just build-tauri-ui`
- `just run-tauri` smoke result
- `just qa-validate`
2. Visual evidence recorded:
- before screenshot(s)
- after screenshot(s)
3. Runtime contract evidence recorded:
- `current_state` invoke command returns valid structured payload.
- `load_active_sprite_pack` invoke command returns manifest/atlas payload.
- `runtime:snapshot` event is observed after command application.
4. API behavior evidence recorded:
- `/v1/health` and `/v1/state` behavior validated against tauri runtime.
- `/v1/command` and `/v1/commands` validated with auth behavior.
5. Docs synchronized:
- issue lifecycle updated
- relevant docs updated when behavior or expectations changed
## Runtime Behavior Checklist
1. Launch tauri runtime via `just run-tauri`.
2. Verify sprite renders in the tauri window.
3. Verify animation advances over time.
4. Send `PlayAnimation` command and verify clip switch is reflected.
5. Send `SetTransform.scale` and verify rendered sprite scale changes.
6. Verify missing animation fallback:
- unknown animation name falls back to `idle` or first available clip.
7. Verify sprite-pack loading:
- valid selected pack loads correctly
- invalid pack path failure is surfaced and runtime remains alive
## API + Runtime Contract Checklist
1. Validate health endpoint:
- `GET /v1/health` returns version/build/capabilities.
2. Validate authenticated state endpoint:
- `GET /v1/state` requires bearer token.
3. Validate command endpoint:
- `POST /v1/command` accepts valid command envelope.
4. Validate batch endpoint:
- `POST /v1/commands` applies commands in order.
5. Validate malformed request resilience:
- malformed JSON returns `400` without process crash.
6. Validate Tauri invoke/event behavior:
- `current_state` output parsed successfully.
- `load_active_sprite_pack` returns expected fields.
- `runtime:snapshot` event received on runtime command changes.
## Evidence Requirements
For each Tauri runtime issue, include:
- command output summaries for all strict gate commands
- screenshot references:
- before: `issues/screenshots/issueN-before-YYYYMMDD-HHMMSS.png`
- after: `issues/screenshots/issueN-after-YYYYMMDD-HHMMSS.png`
- invoke/event verification notes
- API verification notes
## Issue Lifecycle Integration
Use standard lifecycle in `issues/issueN.md`:
1. `Reported`
2. `Triaged`
3. `In Progress`
4. `Fix Implemented`
5. `Verification Passed`
6. `Closed`
Tauri runtime issues must remain at `Fix Implemented` if any strict-gate evidence is missing.
## Failure Classification and Triage
- `P0`: crash on startup, renderer not visible, auth bypass, or command pipeline broken.
- `P1`: animation/state mismatch, event/invoke contract failure, major UX regression.
- `P2`: non-blocking rendering/perf issues, minor UI mismatch, cosmetic defects.
## Test Log Template (Tauri Runtime)
- Date:
- Issue:
- Frontend: `sprimo-tauri`
- Execution mode: `workspace` or `packaged`
- Commands run:
- API checks summary:
- Invoke/event checks summary:
- Before screenshots:
- After screenshots:
- Result:
- Notes: