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