docs: add Caffeine Studio IDE planning (M1-M4 milestones)

Added planning/ directory with detailed task documentation for the
Caffeine Studio IDE — 4 milestones, 29 files total:

planning/caffeine-studio-ide.md          — master plan
planning/m1-scene-editor-foundation/     — 7 tasks (1.1-1.7)
planning/m2-visual-editing-assets/       — 7 tasks (2.1-2.7)
planning/m3-scripting-runtime/           — 7 tasks (3.1-3.7)
planning/m4-advanced-tools-polish/       — 8 tasks (4.1-4.8)

Each task file includes: Visão Geral, Implementação (C++ API + diagrams),
Decisões de Design, Critério de Aceitação, Dependências, Referências.

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: LyeZinho

planning/caffeine-studio-ide.md

@@ -0,0 +1,177 @@
+# 🔧 EditorContext & Undo/Redo
+
+> **Milestone:** M1 — Scene Editor Foundation
+> **Namespace:** `Caffeine::Editor`
+> **Arquivos:** `src/editor/EditorContext.hpp`, `src/editor/EditorContext.cpp`
+> **Status:** 📅 Planeado
+> **RF:** RF6.1
+
+---
+
+## Visão Geral
+
+O `EditorContext` funciona como o cérebro central do editor, mantendo o estado global da sessão atual. Ele armazena informações críticas como a entidade selecionada, o estado de modificação da cena (dirty flag) e o caminho do ficheiro aberto. Sem este contexto, os painéis individuais não teriam uma forma unificada de comunicar mudanças entre si.
+
+O sistema de Undo/Redo é integrado diretamente neste contexto para permitir que o utilizador reverta ações destrutivas ou erros de edição. Ele utiliza um sistema de comandos baseado em estados (snapshots) para garantir que a cena possa regressar exatamente ao ponto anterior a qualquer modificação no ECS.
+
+---
+
+## Implementação
+
+### Estrutura do Comando
+
+Cada comando guarda o estado "antes" e "depois" da modificação para permitir a navegação bidirecional no histórico.
+
+```cpp
+struct EditorCommand {
+    enum Type { 
+        AddEntity, 
+        RemoveEntity, 
+        AddComponent,
+        RemoveComponent, 
+        SetField, 
+        MoveEntity 
+    };
+
+    Type type;
+    ECS::EntityID targetEntity;
+    std::vector<u8> beforeState; // Serialização do componente/entidade antes
+    std::vector<u8> afterState;  // Serialização depois da mudança
+};
+```
+
+### Gestor de Histórico (UndoStack)
+
+Utiliza um buffer circular para evitar alocações constantes e limitar o uso de memória.
+
+```cpp
+class UndoStack {
+    static constexpr u32 MAX_UNDO = 256;
+    EditorCommand m_commands[MAX_UNDO];
+    u32 m_head = 0;   // Onde o próximo comando será inserido
+    u32 m_tail = 0;   // O comando mais antigo disponível
+    u32 m_current = 0; // Posição atual para undo/redo
+    u32 m_count = 0;
+
+public:
+    void push(const EditorCommand& cmd) {
+        m_commands[m_head] = cmd;
+        m_head = (m_head + 1) % MAX_UNDO;
+        
+        if (m_count < MAX_UNDO) {
+            m_count++;
+        } else {
+            m_tail = (m_tail + 1) % MAX_UNDO;
+        }
+        m_current = m_head;
+    }
+
+    bool undo(ECS::World& world) {
+        if (m_current == m_tail) return false;
+        m_current = (m_current - 1 + MAX_UNDO) % MAX_UNDO;
+        applyState(world, m_commands[m_current].beforeState);
+        return true;
+    }
+
+    bool redo(ECS::World& world) {
+        if (m_current == m_head) return false;
+        applyState(world, m_commands[m_current].afterState);
+        m_current = (m_current + 1) % MAX_UNDO;
+        return true;
+    }
+
+    void clear() {
+        m_head = m_tail = m_current = m_count = 0;
+    }
+
+private:
+    void applyState(ECS::World& world, const std::vector<u8>& data);
+};
+```
+
+### EditorContext
+
+O objeto singleton que orquestra a comunicação entre painéis.
+
+```cpp
+class EditorContext {
+public:
+    // Estado da Seleção
+    ECS::EntityID selectedEntity = ECS::INVALID_ENTITY;
+    ECS::EntityID hoveredEntity = ECS::INVALID_ENTITY;
+    ECS::EntityID clipboardEntity = ECS::INVALID_ENTITY;
+
+    // Estado do Gizmo
+    enum class GizmoMode { Translation, Rotation, Scale };
+    GizmoMode currentGizmoMode = GizmoMode::Translation;
+
+    // Estado da Cena
+    std::string currentScenePath = "";
+    bool isDirty = false;
+
+    // Sistemas
+    UndoStack undoStack;
+
+    void selectEntity(ECS::EntityID id) {
+        selectedEntity = id;
+    }
+
+    void markDirty() {
+        isDirty = true;
+    }
+};
+```
+
+### Fluxo de Dados de Undo
+
+```
+[Utilizador Altera Campo] 
+    -> Captura Estado Atual (beforeState)
+    -> Aplica Mudança no ECS
+    -> Captura Novo Estado (afterState)
+    -> EditorContext::undoStack.push(comando)
+    -> EditorContext::markDirty()
+```
+
+---
+
+## Decisões de Design
+
+| Decisão | Justificativa |
+|---------|---------------|
+| Buffer Circular no UndoStack | Evita fragmentação de memória e garante um limite previsível de recursos. |
+| Snapshots de Estado | Mais simples de implementar para o ECS do que comandos delta complexos, aproveitando a serialização existente. |
+| Dirty Flag no Contexto | Centraliza a lógica de aviso de "Guardar Alterações" antes de fechar a aplicação ou mudar de cena. |
+
+---
+
+## Critério de Aceitação
+
+- [ ] Undo/Redo funciona para a criação de entidades (AddEntity).
+- [ ] Undo/Redo funciona para a remoção de entidades (RemoveEntity).
+- [ ] A Dirty Flag é ativada após qualquer ação no histórico.
+- [ ] Selecionar uma entidade atualiza o `selectedEntity` globalmente.
+- [ ] O histórico é limpo ao carregar uma nova cena.
+
+---
+
+## Dependências
+
+- **Upstream:** `docs/ecs/core.md`, `docs/ecs/scene.md`
+- **Downstream:** `1.2-hierarchy-panel.md`, `1.3-inspector-panel.md`, `1.6-scene-editor-orchestrator.md`
+
+---
+
+## 🔗 Tópicos Relacionados
+
+| Tópico | Descrição |
+|--------|-----------|
+| Serialização ECS | Como transformar componentes em bytes para o UndoStack. |
+| Comandos de Editor | Padrão de desenho Command para isolar ações da UI. |
+
+---
+
+## Referências
+
+- [`docs/ecs/core.md`](../docs/ecs/core.md) — Documentação base do sistema de entidades.
+- [Game Programming Patterns - Undo/Redo](https://gameprogrammingpatterns.com/undo-redo.html) — Referência teórica.

planning/m1-scene-editor-foundation/1.1-editor-context-undo-redo.md

@@ -0,0 +1,154 @@
+# 🔧 Hierarchy Panel
+
+> **Milestone:** M1 — Scene Editor Foundation
+> **Namespace:** `Caffeine::Editor`
+> **Arquivos:** `src/editor/HierarchyPanel.hpp`, `src/editor/HierarchyPanel.cpp`
+> **Status:** 📅 Planeado
+> **RF:** RF6.2
+
+---
+
+## Visão Geral
+
+O `HierarchyPanel` é a janela que apresenta a estrutura organizacional de todas as entidades presentes na cena atual. Ele exibe as entidades em formato de árvore, permitindo visualizar relações de parentesco (transform parenting). Este painel é essencial para a navegação rápida, seleção e organização lógica dos objetos de jogo.
+
+Além da visualização, o painel oferece ferramentas para criação, destruição e reordenação de entidades através de interação direta (drag-and-drop) ou menus de contexto.
+
+---
+
+## Implementação
+
+### Estrutura da Classe
+
+O painel utiliza o `EditorContext` para sincronizar a seleção global.
+
+```cpp
+class HierarchyPanel {
+    EditorContext* m_context;
+    char m_searchFilter[256] = "";
+
+public:
+    HierarchyPanel(EditorContext* context) : m_context(context) {}
+
+    void onImGuiRender() {
+        ImGui::Begin("Hierarchy");
+        
+        renderSearchBar();
+        renderToolbar();
+
+        if (ImGui::BeginChild("EntityTree")) {
+            auto view = m_world->view<ECS::NameComponent>();
+            for (auto entity : view) {
+                // Apenas renderiza raízes; filhos são processados recursivamente
+                if (!m_world->has<ECS::ParentComponent>(entity)) {
+                    renderEntityNode(entity);
+                }
+            }
+        }
+        ImGui::EndChild();
+
+        renderContextMenu();
+        
+        ImGui::End();
+    }
+
+private:
+    void renderEntityNode(ECS::EntityID entity) {
+        auto& name = m_world->get<ECS::NameComponent>(entity).name;
+        
+        ImGuiTreeNodeFlags flags = ((m_context->selectedEntity == entity) ? ImGuiTreeNodeFlags_Selected : 0);
+        flags |= ImGuiTreeNodeFlags_OpenOnArrow | ImGuiTreeNodeFlags_SpanAvailWidth;
+        
+        bool hasChildren = checkHasChildren(entity);
+        if (!hasChildren) flags |= ImGuiTreeNodeFlags_Leaf;
+
+        bool opened = ImGui::TreeNodeEx((void*)(uintptr_t)entity, flags, "%s", name.c_str());
+        
+        if (ImGui::IsItemClicked()) {
+            m_context->selectEntity(entity);
+        }
+
+        // Context Menu para a entidade específica
+        if (ImGui::BeginPopupContextItem()) {
+            if (ImGui::MenuItem("Delete")) { m_world->destroy(entity); }
+            ImGui::EndPopup();
+        }
+
+        // Drag and Drop Logic
+        handleDragAndDrop(entity);
+
+        if (opened) {
+            if (hasChildren) {
+                renderChildren(entity);
+            }
+            ImGui::TreePop();
+        }
+    }
+
+    void handleDragAndDrop(ECS::EntityID entity);
+    void renderContextMenu(); // Create empty, etc.
+};
+```
+
+### Lógica de Hierarquia (Parenting)
+
+A hierarquia é mantida através do `ParentComponent` e `ChildrenComponent` (ou uma lista de IDs). No M1, focaremos no `ParentComponent`.
+
+```cpp
+struct ParentComponent {
+    ECS::EntityID parentId;
+};
+```
+
+### Diagrama de Fluxo de Seleção
+
+```
+[HierarchyPanel] Click Node 
+    -> EditorContext::selectEntity(ID)
+    -> [InspectorPanel] Observa mudança 
+    -> [InspectorPanel] Renderiza componentes de ID
+```
+
+---
+
+## Decisões de Design
+
+| Decisão | Justificativa |
+|---------|---------------|
+| `ImGuiTreeNodeFlags_Leaf` para vazios | Fornece feedback visual imediato sobre quais entidades possuem filhos. |
+| Filtro de Pesquisa | Essencial para cenas com centenas de entidades onde a navegação manual é lenta. |
+| Drag-and-Drop Reparenting | Forma mais intuitiva de organizar objetos em 2D/3D. |
+
+---
+
+## Critério de Aceitação
+
+- [ ] Apresenta todas as entidades da cena em formato de lista/árvore.
+- [ ] Clicar numa entidade seleciona-a no `EditorContext`.
+- [ ] Botão direito no vazio abre menu para "Create Empty Entity".
+- [ ] Tecla `Delete` com entidade selecionada remove-a da cena.
+- [ ] O filtro de pesquisa oculta entidades cujos nomes não coincidem com o texto.
+- [ ] Entidades com `ParentComponent` aparecem indentadas sob o pai.
+
+---
+
+## Dependências
+
+- **Upstream:** `1.1-editor-context-undo-redo.md`, `docs/ecs/core.md`
+- **Downstream:** `1.3-inspector-panel.md`, `1.6-scene-editor-orchestrator.md`
+
+---
+
+## 🔗 Tópicos Relacionados
+
+| Tópico | Descrição |
+|--------|-----------|
+| NameComponent | Armazena a string visível no painel. |
+| ECS Parenting | Sistema que sincroniza transformações entre pais e filhos. |
+
+---
+
+## Referências
+
+- [`docs/ui/editor-ui.md`](../docs/ui/editor-ui.md) — Convenções de interface.
+- [ImGui Demo: Tree Nodes](https://github.com/ocornut/imgui/blob/master/imgui_demo.cpp) — Referência de implementação.