[codex] add sprite studio tooling

.agents/skills/borrow-fighters-repo-atlas/references/repo-map.md

@@ -33,6 +33,7 @@
 | `docs/15-character-combat-matrix.md` | Character identity, archetypes and tuning matrix |
 | `docs/16-sprite-combat-viewer-roadmap.md` | Sprite viewer/tooling roadmap for artists and combat alignment |
 | `docs/17-visual-scale-and-stage-metrics.md` | Runtime visual scale, fighter size and arena metrics |
+| `docs/18-sprite-studio.md` | External Tauri + React sprite manifest editor |
 | `docs/adr/` | Architecture Decision Records |
 | `docs/adr/0007-sprite-frame-combat-runtime.md` | Decision for using `frames[].combat` in runtime hit/hurt/projectile origin resolution |
 | `docs/templates/` | Reusable proposal/checklist templates |
@@ -63,6 +64,7 @@
 | `src/math/` | Small geometry helpers |
 | `tests/` | Integration tests for combat, flags and sprites |
 | `tools/art/` | Local asset extraction utilities |
+| `tools/sprite-studio/` | Isolated Tauri + React app for editing sprite manifests |
 
 ## Assets
 

README.md

@@ -35,6 +35,7 @@ A ideia continua sendo evoluir com decisões explícitas, escopo controlado e co
 - [`docs/11-sprite-pipeline.md`](docs/11-sprite-pipeline.md): formato candidato para atlas, animações, pivots e metadata de sprites.
 - [`docs/16-sprite-combat-viewer-roadmap.md`](docs/16-sprite-combat-viewer-roadmap.md): roadmap do viewer para artistas conferirem atlas, pivot, grade e boxes.
 - [`docs/17-visual-scale-and-stage-metrics.md`](docs/17-visual-scale-and-stage-metrics.md): escala visual alvo de personagens, arena e workflow de calibracao.
+- [`docs/18-sprite-studio.md`](docs/18-sprite-studio.md): ferramenta Tauri + React para editar manifestos e atlas fora do loop do jogo.
 - [`docs/templates/mood-proposal.md`](docs/templates/mood-proposal.md): molde para proposta de moodboard.
 - [`docs/templates/character-concept.md`](docs/templates/character-concept.md): molde para personagem e mecânica.
 - [`docs/templates/adr-template.md`](docs/templates/adr-template.md): molde para novas decisões.
@@ -50,6 +51,7 @@ A ideia continua sendo evoluir com decisões explícitas, escopo controlado e co
 - [`docs/15-character-combat-matrix.md`](docs/15-character-combat-matrix.md): matriz de identidade mecânica e tuning inicial de Rust, Duke, Go e C.
 - [`docs/16-sprite-combat-viewer-roadmap.md`](docs/16-sprite-combat-viewer-roadmap.md): ferramenta isolada para inspecionar sprites e preparar hitbox/hurtbox data-driven.
 - [`docs/17-visual-scale-and-stage-metrics.md`](docs/17-visual-scale-and-stage-metrics.md): padrao tecnico de tamanho em tela, escala de sprite e largura de arena.
+- [`docs/18-sprite-studio.md`](docs/18-sprite-studio.md): app desktop externo para artistas editarem `*.sprite.json` com UI propria.
 - [`docs/09-ai-collaboration.md`](docs/09-ai-collaboration.md): como Codex, Claude e skills devem navegar o projeto.
 - [`AGENTS.md`](AGENTS.md): instruções persistentes para Codex.
 - [`CLAUDE.md`](CLAUDE.md): instruções persistentes para Claude Code.
@@ -65,6 +67,7 @@ A ideia continua sendo evoluir com decisões explícitas, escopo controlado e co
 - [`docs/adr/0005-data-driven-audio-events.md`](docs/adr/0005-data-driven-audio-events.md): eventos de áudio data-driven com manifesto JSON.
 - [`docs/adr/0006-runtime-sprite-scale-and-scene-state.md`](docs/adr/0006-runtime-sprite-scale-and-scene-state.md): escala visual por manifesto e maquina de estados de cenas.
 - [`docs/adr/0007-sprite-frame-combat-runtime.md`](docs/adr/0007-sprite-frame-combat-runtime.md): metadata de hitbox/hurtbox por frame no runtime.
+- [`docs/adr/0008-external-sprite-studio-tooling.md`](docs/adr/0008-external-sprite-studio-tooling.md): Sprite Studio externo em Tauri + React, isolado do codigo do jogo.
 
 ### GitHub
 
@@ -174,6 +177,17 @@ cargo run -- --tool sprite-viewer --manifest assets/placeholder/c-fighter.sprite
 
 No Sprite Combat Viewer, use o mouse para inspecionar coordenadas locais do frame, arrastar personagem/dummy e ajustar alças de `frames[].combat`. `N` gera um rascunho de metadata a partir do overlay runtime do golpe selecionado, `Tab` / `Shift+Tab` alterna clip, `Enter` sincroniza clip com golpe, `C` / `Shift+C` alterna personagem de combate, `[` / `]` alterna golpe, `.` / `,` avança ou volta frame, `Espaço` pausa, mouse wheel controla zoom, `0` reseta zoom, `=` / `-` ajusta `scale`, `Setas` ou `Shift+Setas` move o `pivot`, `Ctrl+Setas` ajusta largura/altura do corpo físico, `Ctrl+Shift+Setas` ajusta altura abaixada, `Ctrl+S` salva manifestos de tuning, `O` mostra/esconde dummy, `M` mostra/esconde boxes de combate, `T` mostra/esconde trajetória prevista do projectile, `F5` recarrega manifesto/atlas, `F12` salva screenshot em `target/sprite-viewer-capture.png`, `F9`/`F10` gravam um MP4 local, `G` alterna grade, `P` alterna pivot, `B` alterna bounds, `R` reseta posição e `Esc` volta ao menu quando aberto por `Training`. O padrão de escala fica em [`docs/17-visual-scale-and-stage-metrics.md`](docs/17-visual-scale-and-stage-metrics.md), e o roadmap completo fica em [`docs/16-sprite-combat-viewer-roadmap.md`](docs/16-sprite-combat-viewer-roadmap.md).
 
+O novo Sprite Studio externo vive em `tools/sprite-studio` e deve substituir o viewer Raylib em uma limpeza propria:
+
+```bash
+cd tools/sprite-studio
+pnpm install
+pnpm build
+pnpm tauri dev
+```
+
+Ele usa Tauri 1.8 + React, edita `*.sprite.json` por UI propria, possui file picker nativo, menu desktop, timeline, paineis colapsaveis, tutorial visual, autosave/backup, snap, guias de escala, presets de combat boxes, validacao do runtime e export de review. Detalhes e pre-requisitos ficam em [`docs/18-sprite-studio.md`](docs/18-sprite-studio.md).
+
 Configurações disponíveis em `Versus Setup` e `Options`:
 
 | Preferência | Padrão | Efeito |

docs/08-code-architecture.md

@@ -81,20 +81,23 @@ borrow-fighters/
 │       ├── mod.rs              # Tipos geométricos pequenos do jogo
 │       ├── rect.rs             # Retângulos de colisão/hitbox
 │       └── vec2.rs             # Vetores 2D se Raylib Vector2 não bastar
-└── tests/
-    ├── cli.rs                  # Contrato de argumentos de inicialização
-    ├── characters.rs           # Contrato do registro de personagens
-    ├── combat_lab.rs           # Estado testável do Combat Lab
-    ├── attack_frame_data.rs    # Timing de golpes em frames
-    ├── move_data.rs            # Contrato da tabela MoveSpec
-    ├── character_identity_tuning.rs # Intenção mecânica de Rust/Duke/Go/C por dados
-    ├── combat_rules.rs         # Regras puras de combate e IA
-    ├── traditional_moves.rs    # High/low/throw e ataques aéreos tradicionais
-    ├── cpu_traditional_moves.rs # Cobertura da CPU para golpes tradicionais
-    ├── feature_flags.rs        # Contrato de flags runtime
-    ├── audio_manifest.rs       # Contrato do manifesto e roteamento de áudio
-    ├── sprite_manifest.rs      # Validação do formato JSON de sprites
-    └── sprite_selection.rs     # Clip escolhido a partir do estado do lutador
+├── tests/
+│   ├── cli.rs                  # Contrato de argumentos de inicialização
+│   ├── characters.rs           # Contrato do registro de personagens
+│   ├── combat_lab.rs           # Estado testável do Combat Lab
+│   ├── attack_frame_data.rs    # Timing de golpes em frames
+│   ├── move_data.rs            # Contrato da tabela MoveSpec
+│   ├── character_identity_tuning.rs # Intenção mecânica de Rust/Duke/Go/C por dados
+│   ├── combat_rules.rs         # Regras puras de combate e IA
+│   ├── traditional_moves.rs    # High/low/throw e ataques aéreos tradicionais
+│   ├── cpu_traditional_moves.rs # Cobertura da CPU para golpes tradicionais
+│   ├── feature_flags.rs        # Contrato de flags runtime
+│   ├── audio_manifest.rs       # Contrato do manifesto e roteamento de áudio
+│   ├── sprite_manifest.rs      # Validação do formato JSON de sprites
+│   └── sprite_selection.rs     # Clip escolhido a partir do estado do lutador
+└── tools/
+    ├── art/                    # Utilitarios locais de extracao/ajuste de assets
+    └── sprite-studio/          # App Tauri 1.8 + React isolado para editar manifestos de sprite
 ```
 
 O diretório `scenes/` ainda deve permanecer simples, sem framework de telas. `ui/` já abriga o overlay de debug do Combat Lab, mas ainda não deve virar um sistema genérico antes de haver HUD e menus suficientes para justificar isso. `characters/` já possui o registro mínimo de personagens, mas ainda deve permanecer simples e orientado a dados. Novos módulos só devem entrar quando reduzirem responsabilidade real dos arquivos atuais.
@@ -127,6 +130,20 @@ Deve expor os módulos internos para testes e exemplos. Regras puras de jogo dev
 
 `src/engine/sprites/combat.rs` tambem fica em `engine` porque depende do formato de sprite, clip, pivot e escala visual. Ele nao depende de Raylib; apenas projeta metadata local do atlas para `Rect`/`Vec2` em coordenadas de mundo para que `game::World` possa usar com fallback.
 
+### `tools/sprite-studio`
+
+O Sprite Studio e uma ferramenta externa em Tauri 1.8 + React. Ele nao faz parte do pacote Rust do jogo, nao importa structs do runtime e nao deve virar dependencia do `src/`.
+
+Responsabilidades:
+
+- abrir atlas e `*.sprite.json`;
+- editar dados de manifesto;
+- rodar validacao do runtime por comando externo (`cargo test`) sem linkar codigo do jogo;
+- salvar artefatos consumidos pelo jogo;
+- dar UI melhor para artistas e devs ajustarem pivot, escala, hitbox, hurtbox e origem de projectile.
+
+O contrato entre jogo e ferramenta e apenas o arquivo em disco. A decisao esta registrada em [`docs/adr/0008-external-sprite-studio-tooling.md`](adr/0008-external-sprite-studio-tooling.md).
+
 ### `combat/*`
 
 Deve ser o núcleo mais estável do protótipo. Prioridade:

docs/11-sprite-pipeline.md

@@ -133,11 +133,34 @@ Assets relacionados ao slice atual:
 - `assets/placeholder/arena-java-street.png`
 - `assets/placeholder/arena-terminal-compiler-lab.png`
 
-As ferramentas locais ficam em `tools/art/` e devem ser tratadas como utilitarios de prototipo, nao como pipeline final.
+As ferramentas locais ficam em `tools/art/` e `tools/sprite-studio/`. Scripts em `tools/art/` devem ser tratados como utilitarios de prototipo. O `tools/sprite-studio/` e o app desktop externo para editar manifestos e reduzir a dependencia do viewer Raylib embutido no jogo.
+
+## Sprite Studio
+
+O Sprite Studio vive em [`tools/sprite-studio/`](../tools/sprite-studio) e esta documentado em [`docs/18-sprite-studio.md`](18-sprite-studio.md).
+
+Ele usa Tauri 1.8 + React e nao compartilha codigo com o jogo. O contrato entre ferramenta e runtime e somente o artefato salvo em disco:
+
+- o app edita `*.sprite.json`;
+- o app edita `assets/tuning/character-body-metrics.json`;
+- o jogo carrega `*.sprite.json`;
+- o jogo carrega `assets/tuning/character-body-metrics.json`;
+- testes do jogo validam se o manifesto continua aceito.
+
+Comando:
+
+```bash
+cd tools/sprite-studio
+pnpm install
+pnpm build
+pnpm tauri dev
+```
+
+O Studio oferece file picker nativo, menu desktop, paineis colapsaveis, timeline horizontal, tutorial visual (`F1`), edicao de pivot/scale/boxes/origem, snap, guia de escala visual, presets iniciais de boxes, autosave em `target/sprite-studio-autosave/`, backup em `target/sprite-studio-backups/`, validacao do runtime e export de PNG/JSON para review.
 
 ## Sprite Combat Viewer
 
-O primeiro viewer isolado de sprites vive em:
+O viewer Raylib embutido no jogo continua disponivel temporariamente ate a limpeza dedicada que removera a ferramenta antiga. Ele vive em:
 
 - `src/scenes/sprite_viewer.rs`: estado testavel, carregamento de manifesto, clip/frame atual, playback e drag.
 - `src/engine/render/sprite_viewer.rs`: grid, pivot, bounds e desenho do atlas via Raylib.

docs/12-technical-combat-guide.md

@@ -29,6 +29,7 @@ Sempre que um código novo alterar combate, personagens, input de combate, Comba
 | Combat Lab render | Orquestra Raylib da cena isolada, sprites, grid e projéteis | [`src/engine/render/combat_lab.rs`](../src/engine/render/combat_lab.rs) | Teste manual via Combat Lab |
 | Combat debug UI | Boxes, pivot, dummy, overlay e texto de timing do laboratório | [`src/ui/combat_debug.rs`](../src/ui/combat_debug.rs) | Teste manual via Combat Lab |
 | Sprite Combat Viewer | Ferramenta isolada para carregar atlas em runtime, ver grid, pivot, bounds e preparar boxes data-driven | [`src/scenes/sprite_viewer.rs`](../src/scenes/sprite_viewer.rs), [`src/scenes/sprite_viewer/combat_edit.rs`](../src/scenes/sprite_viewer/combat_edit.rs), [`src/engine/render/sprite_viewer.rs`](../src/engine/render/sprite_viewer.rs) | [`tests/sprite_viewer.rs`](../tests/sprite_viewer.rs), teste manual via `--tool sprite-viewer` |
+| Sprite Studio | App externo Tauri 1.8 + React para editar manifestos sem depender de Raylib | [`tools/sprite-studio`](../tools/sprite-studio) | `pnpm build`; `pnpm tauri build --debug`; desktop requer pre-requisitos Tauri |
 | Input | Teclado/gamepad para luta, menu, Sprite Viewer e Combat Lab | [`src/engine/input.rs`](../src/engine/input.rs), [`src/engine/gamepad.rs`](../src/engine/gamepad.rs) | [`tests/cli.rs`](../tests/cli.rs), [`tests/feature_flags.rs`](../tests/feature_flags.rs) |
 | Sprite runtime | Manifest JSON, clip selection, projeção de `frames[].combat` e desenho por pivot | [`src/engine/sprites/`](../src/engine/sprites), [`src/engine/sprites/combat.rs`](../src/engine/sprites/combat.rs) | [`tests/sprite_manifest.rs`](../tests/sprite_manifest.rs), [`tests/sprite_selection.rs`](../tests/sprite_selection.rs) |
 
@@ -74,7 +75,7 @@ Hitboxes:
 
 Essa técnica foi escolhida porque é legível, testável sem Raylib e suficiente para o Prototype 0.1. Quando o frame visual declara `frames[].combat`, o runtime projeta esses dados para coordenadas de mundo em [`src/engine/sprites/combat.rs`](../src/engine/sprites/combat.rs). A resolução da luta usa `frames[].combat.hitboxes[]` e `frames[].combat.hurtboxes[]` quando essas listas existem; se estiverem ausentes ou vazias, volta para `MoveSpec.hitbox` e `Fighter::hurtboxes()`. A decisão está registrada em [`docs/adr/0007-sprite-frame-combat-runtime.md`](adr/0007-sprite-frame-combat-runtime.md).
 
-Rust, Duke, Go e C ja possuem `combat.projectile_origin` no primeiro frame do clip `special`. Esse ponto e projetado por [`src/engine/sprites/combat.rs`](../src/engine/sprites/combat.rs) e usado por [`src/game/world.rs`](../src/game/world.rs) ao criar o projectile, para evitar que o poder nasca desalinhado da mao. Rust `Borrow Jab`, heavy punch e kick ja possuem hitboxes de frame; os valores ainda reproduzem o alcance do `MoveSpec` para migrar com baixo risco. Hitboxes/hurtboxes restantes ainda devem ser calibradas no Sprite Combat Viewer antes de virar dado autoritativo.
+Rust, Duke, Go e C ja possuem `combat.projectile_origin` no primeiro frame do clip `special`. Esse ponto e projetado por [`src/engine/sprites/combat.rs`](../src/engine/sprites/combat.rs) e usado por [`src/game/world.rs`](../src/game/world.rs) ao criar o projectile, para evitar que o poder nasca desalinhado da mao. Rust `Borrow Jab`, heavy punch e kick ja possuem hitboxes de frame; os valores ainda reproduzem o alcance do `MoveSpec` para migrar com baixo risco. Hitboxes/hurtboxes restantes devem ser calibradas no Sprite Studio, com o Sprite Combat Viewer Raylib apenas como ferramenta temporaria ate a limpeza dedicada.
 
 ### Escala Visual e Pivot
 
@@ -97,9 +98,10 @@ O padrao de tamanho em tela fica em [`docs/17-visual-scale-and-stage-metrics.md`
 - personagens nao-humanos, como Go, devem mirar a mesma faixa principal quando a diferenca de tamanho nao for parte do gameplay;
 - a arena atual tem `896 px` jogaveis, cerca de `11,8` larguras de corpo padrao.
 
-Use o Sprite Combat Viewer para calibrar:
+Use o Sprite Studio para edicao visual confortavel e validacao de runtime. O Sprite Combat Viewer embutido continua disponivel apenas ate a limpeza dedicada:
 
 ```bash
+cd tools/sprite-studio && pnpm tauri dev
 cargo run -- --tool sprite-viewer --manifest assets/placeholder/go-fighter.sprite.json --clip idle --character go --move light_punch
 cargo run -- --tool sprite-viewer --manifest assets/placeholder/c-fighter.sprite.json --clip idle --character c --move light_punch
 ```
@@ -353,6 +355,8 @@ Poses atuais:
 
 ### Sprite Combat Viewer
 
+O Sprite Combat Viewer Raylib e ferramenta temporaria. A direcao aprovada em [`docs/adr/0008-external-sprite-studio-tooling.md`](adr/0008-external-sprite-studio-tooling.md) e mover a edicao rica para [`tools/sprite-studio`](../tools/sprite-studio). A paridade operacional ja existe; o viewer embutido deve ser removido em uma mudanca propria.
+
 Abrir a ferramenta isolada de sprites:
 
 ```bash

docs/16-sprite-combat-viewer-roadmap.md

@@ -2,15 +2,17 @@
 
 ## Status
 
-Em implementacao inicial na branch `tooling/sprite-combat-viewer`.
+Implementado como ferramenta Raylib temporaria. O sucessor e o Sprite Studio externo em Tauri + React, documentado em [`docs/18-sprite-studio.md`](18-sprite-studio.md) e decidido em [`docs/adr/0008-external-sprite-studio-tooling.md`](adr/0008-external-sprite-studio-tooling.md).
+
+O Sprite Studio ja possui paridade operacional para abrir, editar, validar e exportar review de manifestos. O viewer Raylib deve ser removido em uma mudanca propria.
 
 Issue de rastreio: [#15](https://github.com/osdeving/borrow-fighters/issues/15).
 
 ## Objetivo
 
 Criar uma ferramenta leve para artistas e devs verificarem sprites, pivots, alinhamento visual, escala e, nas proximas fases, hitbox, hurtbox, origem de projectile e dummy de contato sem entrar no fluxo normal de luta.
 
-O viewer nao deve ser tratado como editor final. Ele e uma ferramenta plugavel de producao para reduzir tentativa e erro ao criar atlas e ajustar manifestos.
+O viewer nao deve ser tratado como editor final. Ele foi uma ferramenta plugavel para reduzir tentativa e erro ao criar atlas e ajustar manifestos. A direcao atual e mover a experiencia de edicao rica para o Sprite Studio externo.
 
 ## Por Que Nao Basta o Combat Lab
 
@@ -27,16 +29,14 @@ O Sprite Combat Viewer fica um nivel antes: ele inspeciona o asset e seus dados.
 
 ## Pesquisa de GUI
 
-Para o primeiro corte, Raylib puro e suficiente: grade, linhas, mouse drag, texto e atalhos de teclado cobrem a inspecao basica.
-
-Se a ferramenta passar a precisar de painel lateral com checkboxes, sliders, listas e inputs editaveis, a opcao candidata e `raygui`, biblioteca immediate-mode criada para o ecossistema raylib. O crate `raylib` 6.0 tambem expoe uma feature `raygui`, entao o caminho tecnico existe sem trocar stack.
+Raylib puro foi suficiente para grade, linhas, mouse drag, texto e atalhos de teclado. A partir do momento em que a ferramenta passou a precisar de painel lateral, checkboxes, sliders, listas, inputs editaveis e fluxo de artista, a decisao mudou para Tauri + React.
 
 Decisao atual:
 
-- usar Raylib puro no corte inicial;
-- evitar `egui`/`imgui` enquanto a ferramenta couber em primitives;
-- avaliar `raygui` na Fase 2 ou 3 se os controles por tecla ficarem insuficientes;
-- nao salvar arquivos automaticamente antes de termos consenso sobre schema de boxes.
+- manter Raylib viewer apenas ate a branch de remocao dedicada;
+- evoluir UI rica no Sprite Studio;
+- nao introduzir `raygui`, `egui` ou `imgui` dentro do jogo neste momento;
+- remover o viewer Raylib quando o Sprite Studio conseguir salvar manifestos aceitos pelo jogo.
 
 Referencias: