Sprimo/docs/TAURI_FRONTEND_DESIGN.md

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)
  • settings commands:
    • settings_snapshot
    • list_sprite_packs
    • set_sprite_pack
    • set_scale
    • set_visibility
    • set_always_on_top
  • debug_overlay_visible / set_debug_overlay_visible commands for persisted debug panel control
  • runtime:snapshot event after command application.
• React/Vite frontend now renders sprite atlas frames with PixiJS and updates animation/scale from runtime snapshot events.
• For sprite.png packs in tauri runtime, frame size is now derived from atlas dimensions with a fixed 8x7 grid topology to keep splitting stable across packaged asset resolutions.
• sprite.png animation naming now follows row semantics with backward-compatible aliases:
  • row1: idle
  • row2: happy/love + alias active
  • row3: excited/celebrate + alias success
  • row4: sleepy/snoring
  • row5: working
  • row6: angry/surprised/shy + alias error
  • row7: dragging
• React/Vite frontend now supports two window modes:
  • main: transparent overlay sprite renderer
  • settings: pop-out settings window for character and window controls
• Tauri window drag is implemented for undecorated mode:
  • left-mouse drag starts native window dragging
  • moved position is synced into runtime-core snapshot/config state.
• Windows-first tray/menu MVP is implemented:
  • Settings (opens/focuses pop-out settings window)
  • Show/Hide
  • Always on top toggle
  • Debug overlay toggle
  • Quit
• Bevy frontend remains intact.
• Runtime QA workflow is defined in docs/TAURI_RUNTIME_TESTING.md.

Remaining Work

1. Extend tray/menu implementation beyond Windows-first MVP and close platform parity gaps.
2. Add frontend parity acceptance tests (Bevy vs Tauri state transitions).
3. Add sprite-pack previews/thumbnails in the settings window character selector.