---
id: AGD-0009
ticket: studio-debugger-workspace-integration
title: Integrar ../debugger ao Studio como workspace dedicado
status: open
created: 2026-03-30
resolved:
decision:
tags:
  - studio
  - debugger
  - workspace
  - integration
  - shell
---

## Pain

O shell do Studio ja anuncia `WorkspaceId.DEBUG` e exibe `Debug` na workspace rail, mas nao registra nenhum workspace concreto para esse slot.

Hoje isso deixa o produto num estado inconsistente:

- a shell promete um `Debugger/Profiler` como workspace baseline;
- `MainView` publica a opcao `Debug` na navegacao;
- `WorkspaceHost` exige que o workspace esteja registrado;
- a implementacao real do `Debug` continua fora do Studio, no sibling repo `../debugger`.

Sem uma discussion canonica, a integracao tende a cair em um de tres atalhos ruins:

- abrir o debugger como app externo e fingir que isso equivale a um workspace;
- embutir a aplicacao JavaFX existente dentro do Studio sem alinhar ciclo de vida, eventos e theming;
- reescrever tudo no Studio e perder o que o `../debugger` ja estabilizou em protocolo, controle de execucao e estado.

## Context

Domain owner: `studio`
Owner surface: `docs/specs/studio`
Cross-domain input: sibling repo `../debugger`

Superficies relevantes hoje:

- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` ja define `Debugger/Profiler` como parte do baseline workspace set;
- `docs/specs/studio/2. Studio UI Foundations Specification.md` exige um modelo de workspaces orientado a eventos, com bus por workspace e republishing para o bus global;
- `prometeu-studio/src/main/java/p/studio/window/MainView.java` ja inclui `WorkspaceId.DEBUG` na rail, mas o `register(...)` correspondente esta comentado;
- `prometeu-studio/src/main/java/p/studio/workspaces/Workspace.java` exige um contrato de `rootNode()`, `load()`, `unLoad()` e integra o workspace a um `StudioWorkspaceEventBus`;
- `../debugger` ja existe como aplicacao JavaFX separada, com `Application`/`Stage`, FXML, Dagger, i18n, cliente DevTools, protocolo TCP/JSONL e controle de execucao.

O boundary de produto tambem ja aponta a direcao correta:

- o shell do Studio deve enquadrar workspaces sem absorver detalhe operacional;
- logs e detalhe de execucao pertencem ao workspace que os possui;
- o debugger e uma superficie de execucao, nao um detalhe lateral do painel global de utilidades.

## Open Questions

- [ ] O objetivo da primeira integracao e hospedar a experiencia atual do `../debugger` quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio?
- [ ] Quais partes do `../debugger` sao `core` reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira?
- [ ] Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo?
- [ ] Quem passa a ser o owner do ciclo de vida da sessao de debug: o `DebugWorkspace`, a shell do Studio, ou um servico compartilhado com a run surface?
- [ ] Como eventos, telemetria, logs e estados do debugger entram no bus de workspace e no bus global sem criar um segundo sistema paralelo de notificacao?
- [ ] O primeiro corte deve incluir `profiler` junto com `debugger`, ou o baseline inicial fecha apenas `debugger` e deixa profiling como extensao posterior?
- [ ] Como preservar tema, i18n e consistencia visual se parte da UI atual do `../debugger` ainda estiver em FXML e recursos proprios?
- [ ] O app standalone `../debugger` continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario?

## Options

### Option A - Launcher externo a partir do Studio
- **Approach:** O Studio oferece um ponto de entrada para abrir `../debugger` como processo/janela externa, mantendo a integracao dentro da shell apenas como acao de lancamento.
- **Pro:** Menor custo inicial e reaproveitamento maximo da app atual.
- **Con:** Nao entrega um workspace real do Studio, fragmenta estado/sessao e conflita com a baseline shell spec.
- **Maintainability:** Fraca como arquitetura final. Pode servir no maximo como ponte temporaria, mas nao resolve o contrato de workspace.

### Option B - Embutir a UI atual do debugger quase inteira dentro de um workspace host
- **Approach:** Reaproveitar FXML/controllers do `../debugger` e monta-los dentro de um `DebugWorkspace`, fazendo adaptacoes localizadas de DI, lifecycle e navegacao.
- **Pro:** Reaproveita mais UI existente e acelera a primeira tela funcional.
- **Con:** Carrega para dentro do Studio um bootstrap orientado a `Application`/`Stage`, com modelo proprio de lifecycle, theming e eventos que nao casa naturalmente com o contrato de workspace atual.
- **Maintainability:** Media para baixa. Economiza reescrita imediata, mas cristaliza um boundary torto entre app standalone e workspace embutido.

### Option C - Workspace nativo do Studio apoiado em core extraido do debugger
- **Approach:** Tratar o `../debugger` como fonte de servicos, protocolo, estado e controle de execucao reaproveitaveis, mas implementar o `DebugWorkspace` como composicao nativa do Studio sobre o contrato `Workspace` + bus tipado + lifecycle-managed controls.
- **Pro:** Alinha shell spec, workspace framework e boundary de produto, sem descartar o investimento ja feito no debugger.
- **Con:** Exige separar explicitamente o que e `core` reutilizavel e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico.
- **Maintainability:** Forte. Preserva a direcao arquitetural correta e permite que Studio e app standalone compartilhem nucleo sem colapsarem num acoplamento acidental.

### Option D - Migracao integral do debugger para dentro do Studio
- **Approach:** Absorver codigo e UI do `../debugger` para dentro dos modulos do Studio e tratar a aplicacao standalone como legado a ser aposentado.
- **Pro:** Simplifica ownership futuro se o produto decidir convergir totalmente para uma unica shell.
- **Con:** E a aposta mais cara e mais irreversivel, antes mesmo de fechar o contrato de integracao e o que ainda deve continuar independente.
- **Maintainability:** Media. Pode ser boa no longo prazo, mas e prematura enquanto o boundary entre `workspace` e `app standalone` ainda nao esta fechado.

## Discussion

O ponto principal nao e "como mostrar alguma tela de debug no Studio". O ponto principal e decidir qual contrato queremos estabilizar entre:

- a shell do Studio, que ja assume workspaces independentes e orientados a eventos;
- o `DebugWorkspace`, que precisa ser um workspace real, com ownership claro de detalhe operacional;
- e o `../debugger`, que hoje concentra bootstrap de app, protocolo, estado e UI numa aplicacao separada.

O fato de a rail ja ter `Debug` e a spec ja falar em `Debugger/Profiler` indica que a integracao nao e trabalho especulativo.
Ela ja faz parte da topologia esperada do Studio.

Por isso, as opcoes que preservam o debugger apenas como janela externa ou que arrastam a app inteira para dentro do host sem remodelar o boundary resolvem pouco:

- a primeira evita o trabalho agora, mas nao entrega o produto prometido pela shell;
- a segunda reaproveita UI, mas importa um modelo arquitetural que nao conversa bem com `Workspace`, `StudioWorkspaceEventBus`, theming compartilhado e lifecycle-managed controls.

O caminho mais coerente parece ser separar o problema em duas camadas:

1. um `debugger core` reaproveitavel, com sessao, protocolo, telemetria, logs e controle de execucao;
2. uma composicao de `DebugWorkspace` nativa do Studio, que consome esse core como mais um workspace do shell.

Isso nao obriga uma reescrita total imediata da logica do debugger.
Obriga apenas que a UI e o bootstrap standalone parem de ser tratados como se fossem a fronteira certa de integracao.

## Resolution

Recommended direction: seguir com **Option C**.

A agenda deve convergir para uma decisao com os seguintes fechamentos:

1. `Debug` no Studio deve virar um workspace real, nao apenas launcher de app externo;
2. o boundary correto de reaproveitamento esta em servicos/protocolo/estado do debugger, nao no bootstrap `Application`/`Stage` como unidade de integracao;
3. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n;
4. o destino do app standalone precisa ser explicitado: consumidor paralelo do mesmo core durante migracao, ou superficie secundaria apos a integracao;
5. o primeiro corte deve declarar se `profiler` entra junto com `debugger` ou fica explicitamente fatiado para depois.

Next step suggestion: converter esta agenda em uma `decision` que feche o modelo de integracao, o boundary de ownership entre `studio` e `../debugger`, a topologia de dependencias entre repositorios e o escopo da primeira wave de `DebugWorkspace`.