editor workspace foundation

This commit is contained in:
2026-03-30 23:44:34 +01:00
parent 66e9d2353c
commit fb266a41e4
8 changed files with 762 additions and 53 deletions
@@ -4,8 +4,8 @@ ticket: studio-code-editor-workspace-foundations
title: Iniciar foundations do Code Editor no Studio sem LSP
status: open
created: 2026-03-30
resolved:
decision:
resolved: 2026-03-30
decision: DEC-0008
tags:
- studio
- editor
@@ -16,14 +16,15 @@ tags:
## Pain
O shell do Studio ja assume `Code Editor` como parte do baseline workspace set, mas a implementacao atual do `EditorWorkspace` ainda e apenas um `CodeArea` com texto hardcoded e botoes sem modelo real de documento, tabs, arquivos, dirty state ou sessao de projeto.
O shell do Studio ja assume `Code Editor` como parte do baseline workspace set, mas a implementacao atual do `EditorWorkspace` ainda e apenas um `CodeArea` com texto hardcoded e botoes sem modelo real de documento, tabs, arquivos, modo read-only organizado ou sessao de projeto.
Ao mesmo tempo, queremos iniciar os trabalhos do editor agora, com foco em UI e infraestrutura robusta para varios frontends, mas sem cair em uma dependencia prematura de LSP.
Ao mesmo tempo, queremos iniciar os trabalhos do editor agora, com foco em UI e infraestrutura robusta para varios frontends, mas sem cair em uma dependencia prematura de LSP e sem fechar a porta para ele como provedor semantico futuro.
Sem fechar a boundary agora, a implementacao pode desviar para dois extremos ruins:
Sem fechar a boundary agora, a implementacao pode desviar para tres extremos ruins:
- o Studio virar uma casca quase vazia que depende de cada frontend ate para abrir, salvar e manter buffers;
- ou o Studio absorver semantica demais e virar uma segunda autoridade sobre parsing, diagnosticos e modelo de compilacao.
- ou a primeira wave endurecer a arquitetura em torno de uma implementacao local que depois conflita com a integracao de LSP.
## Context
@@ -38,31 +39,39 @@ Superficies relevantes hoje:
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java` hoje monta um `CodeArea` simples sem modelo de arquivos do projeto;
- `prometeu-studio/src/main/java/p/studio/projects/ProjectLanguageCatalogService.java` ja consome `FrontendRegistryService` e `FrontendSpec`, o que mostra que o Studio ja reconhece multiplos frontends e source roots por linguagem;
- `prometeu-compiler/.../FrontendSpec.java` ja modela `languageId`, `allowedExtensions`, `sourceRoots`, `caseSensitive` e versoes de stdlib;
- o compiler hoje ainda descobre e le fontes diretamente do filesystem: `LoadSourcesPipelineStage` faz `walkFileTree(...)` nos `sourceRoots`, `BuilderPipelineContext.compilerContext(...)` instancia `SourceProviderFactory.filesystem()`, e `SourceHandle` le bytes com `Files.readAllBytes(path)`;
- `DSC-0011` acabou de fechar que o compiler possui entrypoints canonicos `analyze`, `compile` e `build`, com `analyze` como superficie sem write side effects e `AnalysisSnapshot` como contrato minimo de resultado;
- `docs/roadmaps/lsp/` ja existe como trilha separada, mas esta wave quer editor sem depender de LSP;
- o precedente do packer fixa uma boa disciplina de ownership, mas ele nao deve ser copiado mecanicamente para o editor sem discutir a diferenca entre semantica de dominio e sessao generica de edicao.
O ponto mais sensivel desta agenda e justamente essa diferenca:
- no packer, Studio nao deve reinventar semantica de asset, snapshots operacionais ou write lanes de dominio;
- no editor, leitura/escrita de arquivos fonte, dirty tracking, buffers em memoria e snapshots documentais fazem parte da propria experiencia do workspace e nao sao, por si so, semantica de linguagem.
- no editor, leitura de arquivos fonte, buffers em memoria para arquivos abertos e snapshots documentais/estruturais fazem parte da propria experiencia do workspace e nao sao, por si so, semantica de linguagem.
Direcao adicional ja explicitada para a UX:
- o editor deve seguir um baseline proximo ao modelo do IntelliJ;
- a ala esquerda deve ser um `Project Navigator` com arquivos/pastas relevantes do projeto;
- a ala esquerda deve ser uma stack vertical com `Project Navigator` funcional no topo e uma regiao de `Outline` ja delimitada abaixo, ainda apenas como placeholder estrutural nesta wave;
- o `Project Navigator` deve mostrar todos os arquivos e diretorios do projeto, com tagging visual dos source roots relevantes para o frontend selecionado em `prometeu.json`;
- o `Project Navigator` deve ordenar pastas antes de arquivos, em ordem alfabetica, sem filtros sofisticados nesta wave, incluindo arquivos ocultos por padrao;
- a area central deve ter tabs de arquivos abertos no topo e o editor rico no corpo principal;
- a regiao inferior deve ser um helper persistente para prompts, tips e feedback contextual sobre o codigo atual, funcionando mais como `advanced editor log` do que como console cru.
- a regiao inferior deve ser um helper persistente apenas para demarcar espaco nesta wave, funcionando como placeholder passivo;
- a primeira wave tambem pode incluir um `status bar` passivo: breadcrumb do arquivo ativo na esquerda e, na direita, `L:C`, line separator, modo de tabs/espacos, extensao/linguagem e um cadeado de `read-only` apenas visual, sem efeito funcional ainda; `L:C` pode nascer como placeholder visual nesta wave.
## Open Questions
- [ ] Qual e o seam normativo para ligar `document snapshots` do editor ao compiler: substituir `SourceProviderFactory.filesystem()` por provider de sessao, ou introduzir uma etapa explicita que materializa uma visao congelada de documentos antes do pipeline?
- [ ] O primeiro wave do editor deve nascer com tabs multiplas e sessao multi-documento completa, ou tabs multiplas com uma politica mais simples de documentos ativos/carregados?
- [ ] Como o `EditorWorkspace` descobre quais arquivos e source roots sao editaveis a partir de `ProjectReference.languageId` e `FrontendSpec`?
- [ ] Quem detecta modificacoes externas em arquivos abertos e como o conflito entre disco e buffer em memoria deve aparecer para o usuario?
- [ ] Alem do baseline ja aceito (`Project Navigator`, tabs, editor central, helper inferior), a primeira wave tambem deve incluir `outline` ou `status bar`, ou esses elementos ficam explicitamente para depois?
- [ ] Como preservar uma UI consistente entre linguagens diferentes sem forcar cada frontend a carregar seu proprio mini-editor completo?
- [ ] O que fica explicitamente fora desta wave por ausencia de LSP: autocomplete, go to definition, semantic diagnostics ao digitar, symbols, rename, code actions?
- [x] O primeiro wave do editor deve nascer com tabs multiplas e sessao multi-documento completa, ou tabs multiplas com uma politica mais simples de documentos ativos/carregados?
Fechamento: todo arquivo ainda nao aberto deve abrir em nova tab; a primeira wave tera uma faixa de tabs responsiva, mostrando quantas tabs couberem na largura disponivel e mandando o restante para um controle de overflow no estilo IntelliJ; a tab ativa deve permanecer visivel; comportamento mais rico pode ser adicionado depois.
- [x] Como o `EditorWorkspace` descobre quais arquivos e source roots sao editaveis a partir de `ProjectReference.languageId` e `FrontendSpec`?
Fechamento: o editor pode abrir todos os arquivos do projeto; `prometeu.json` define o frontend selecionado e serve para taggear corretamente os source roots/diretorios fonte no `Project Navigator`; a wave continua read-only.
- [x] Quem detecta modificacoes externas em arquivos abertos e como o conflito entre disco e buffer em memoria deve aparecer para o usuario?
Fechamento: o projeto recebe um refresh inicial ao abrir e aceita refresh manual a qualquer momento por um botao proprio no `Project Navigator`; como a wave e read-only, nao existe resolucao de merge local ainda.
- [x] Alem do baseline ja aceito (`Project Navigator`, tabs, editor central, helper inferior), a primeira wave tambem deve incluir `outline` ou `status bar`, ou esses elementos ficam explicitamente para depois?
Fechamento: `status bar` entra nesta wave; `outline` fica fora como componente funcional, mas sua regiao ja deve ficar delimitada visualmente abaixo do `Project Navigator` como placeholder estrutural.
- [x] Qual e o modelo de eventos editoriais minimo desta wave: arquivo aberto/fechado, troca de tab ativa, dirty state, save, reload externo, erro de IO e mudanca de selecao no navigator?
Fechamento: esta agenda nao vai fechar um contrato formal de eventos agora; se necessario, deixar apenas comentarios de implementacao, nao requisitos normativos.
- [x] O que fica explicitamente fora desta wave por ausencia de LSP: autocomplete, go to definition, semantic diagnostics ao digitar, symbols, rename, code actions?
Fechamento: esta wave nao lida com codigo em si, apenas com gerenciamento de arquivos, abertura de tabs e composicao editorial do workspace.
## Options
@@ -72,10 +81,10 @@ Direcao adicional ja explicitada para a UX:
- **Con:** Duplica infraestrutura generica em cada frontend, acopla UX basica a backend de linguagem e torna dificil sustentar uma experiencia coerente multi-FE sem LSP.
- **Maintainability:** Fraca. A boundary fica formalmente limpa, mas o custo reaparece como fragmentacao de sessao, inconsistencias de UX e adaptadores repetidos.
### Option B - Studio possui sessao generica de documentos; frontends possuem semantica
- **Approach:** O Studio passa a possuir uma camada generica de editor para descoberta de arquivos, open/save, dirty tracking, tabs, estado ativo, deteccao de mudanca externa e snapshots imutaveis de documento em memoria; frontends consomem essa camada como entrada para highlighting, parsing, diagnosticos e outras features atuais ou futuras.
### Option B - Studio possui sessao generica de documentos; semantica vem depois por integracao
- **Approach:** O Studio passa a possuir uma camada generica de editor para descoberta de arquivos, leitura, tabs, estado ativo, refresh manual, snapshot estrutural da arvore e gerenciamento dos documentos abertos em memoria em modo read-only; provedores semanticos futuros, incluindo LSP, consomem essa base depois por uma seam explicita.
- **Pro:** Cria uma base robusta para varios frontends mesmo sem LSP, evita duplicacao de infra generica e mantem a semantica de linguagem fora do workspace visual.
- **Con:** Exige disciplina para nao confundir `snapshot documental` com `snapshot semantico` do compiler e para nao deixar a camada generica vazar regras de linguagem.
- **Con:** Exige disciplina para nao confundir `snapshot documental` com resultado semantico e para nao deixar a camada generica vazar regras de linguagem ou hardcodes anti-LSP.
- **Maintainability:** Forte. A separacao entre sessao de edicao e semantica de linguagem fica clara e expansivel.
### Option C - Cada frontend possui seu proprio stack de editor end-to-end
@@ -108,8 +117,6 @@ No editor de codigo, porem, existe uma camada anterior a qualquer semantica de l
- abrir arquivo;
- manter buffer em memoria;
- controlar dirty state;
- salvar em disco;
- alternar tabs;
- versionar snapshots documentais;
- reagir a mudancas externas;
@@ -124,41 +131,92 @@ Do ponto de vista de UX, a direcao mais solida e assumir um baseline de tres reg
2. `Editor Workarea` no centro, com tabs acima e editor no corpo
3. `Editor Helper Panel` na base, para tips, prompts, hints e feedback contextual
Esse painel inferior merece cuidado de nomenclatura e ownership.
Ele nao deve nascer como "console generico" nem como dumping ground de logs tecnicos.
Melhor trata-lo como uma superficie editorial guiada pelo contexto do documento ativo.
Dentro da coluna esquerda, o layout ja deve nascer preparado para a composicao futura:
Sugestao de papel para esse helper:
1. `Project Navigator` funcional no topo;
2. regiao de `Outline` reservada abaixo;
3. `Outline` ainda sem comportamento real, sem arvore fake e sem semantica local nesta wave.
- mostrar hints sobre arquivo, linguagem e estado do documento;
- receber mensagens de parse/local validation quando existirem;
- explicar bloqueios de save, conflitos de disco e prompts do editor;
- no futuro, acomodar saidas de LSP ou FE sem acoplar a shell global a isso.
Em outras palavras: ele deve ser um `assistant/log` de workspace, nao um substituto do painel global `Activity` e nao um terminal cru.
Esse painel inferior ainda nao precisa nascer com funcao real.
Nesta wave ele existe apenas para demarcar o espaco futuro da composicao, como placeholder passivo.
O boundary mais saudavel parece ser:
1. o Studio possui a sessao generica de documentos e a UX editorial comum;
2. os frontends recebem snapshots documentais imutaveis como entrada;
2. essa sessao cobre organizacao de componentes, buffers abertos em memoria, tabs, refresh/reload e o minimo necessario para gerenciamento editorial read-only dos arquivos;
3. parsing, name resolution, diagnostics, semantic tokens, completions e afins continuam fora da camada generica do editor;
4. LSP, quando existir, entra como um consumidor/provedor de semantica sobre essa base, nao como substituto da base.
4. LSP, quando existir, entra como um provedor de semantica sobre essa base, nao como substituto da base e nao como dependencia obrigatoria desta wave.
O estado atual do compiler reforca essa necessidade.
Hoje o build pipeline ainda assume filesystem como source of truth imediata:
- os arquivos sao descobertos por crawl direto nos `sourceRoots`;
- o `BuilderPipelineContext` nasce com `SourceProviderFactory.filesystem()`;
- cada `SourceHandle` le bytes do `Path` canonico.
Isso significa que, se quisermos uniformizar Studio, FE services e LSP futuro em torno de uma mesma visao documental, precisamos introduzir explicitamente uma camada de `document snapshot` antes do consumo pelo pipeline.
O lado bom e que ja existe um seam util: `SourceProviderFactory` nao esta hardcoded em todos os callsites e ja sugere providers alternativos, inclusive `in-memory`.
O estado atual do compiler ajuda a nao exagerar o escopo desta agenda.
`DSC-0011` fechou o pipeline canonico e os entrypoints publicos do compiler.
Isso e suficiente, por enquanto, para esta agenda assumir apenas que o editor nao deve bloquear integracoes semanticas futuras.
Esta discussion nao precisa decidir agora o contrato final entre `document snapshots` e `analyze`, nem substituir LSP por uma semantica local improvisada no Studio.
Isso tambem ajuda com a meta de varios FEs:
- `FrontendSpec` ja informa roots e extensoes;
- o `EditorWorkspace` pode montar a superficie a partir disso;
- e cada linguagem fica livre para plugar servicos sem destruir o modelo editorial comum.
- e cada linguagem ou integracao futura fica livre para plugar semantica sem destruir o modelo editorial comum.
Com isso, o foco desta agenda fica mais limpo:
1. composicao visual do workspace editor;
2. gerenciamento de arquivos abertos em memoria;
3. modelo de tabs e documento ativo;
4. refresh em modo read-only;
5. `Project Navigator` completo sobre o projeto com tagging de source roots relevantes;
6. `status bar` passivo com informacoes editoriais basicas;
7. reserva de seams para providers semanticos futuros, sem acoplamento prematuro.
Tabs precisam nascer de forma pragmatica nesta wave.
O objetivo nao e fechar ainda persistencia de sessao, drag-and-drop, pinning, grupos, split view ou navegacao avancada.
O que fica fechado e o baseline visual e operacional:
1. arquivos ainda nao abertos entram em nova tab;
2. a faixa de tabs deve ser responsiva e mostrar quantas tabs couberem na largura disponivel;
3. tabs adicionais devem ficar acessiveis por um controle de overflow estilo IntelliJ;
4. a tab ativa deve permanecer visivel;
5. o rotulo da tab usa apenas o nome do arquivo com extensao;
6. comportamento mais rico pode ser adicionado depois sem mudar o contrato visual inicial.
O `Project Navigator` tambem fica mais claro:
1. ele nao deve limitar a edicao apenas aos arquivos fonte tagged;
2. ele deve mostrar todos os arquivos e diretorios do projeto;
3. `prometeu.json` e o frontend selecionado servem para destacar roots relevantes, nao para esconder o restante do projeto.
4. ele deve manter um snapshot estrutural em memoria da arvore do projeto para navegacao e estado visual;
5. esse snapshot estrutural nao substitui o filesystem como source of truth;
6. snapshots de conteudo continuam restritos aos arquivos abertos no editor;
7. a arvore faz um refresh inicial ao abrir o projeto e permite refresh manual a qualquer momento por um botao proprio;
8. arquivos ocultos entram por padrao;
9. arquivos nao-textuais ou nao suportados podem aparecer no navigator, mas devem abrir um modal simples avisando que o arquivo nao e suportado nesta wave.
A regiao de `Outline` deve entrar apenas como reserva estrutural.
Ela ajuda a estabilizar a composicao da coluna esquerda agora, sem puxar semantica prematura para dentro desta agenda.
Se houver texto placeholder, ele deve ser discreto e claramente nao funcional.
O `status bar` entra como componente editorial passivo nesta primeira wave.
Na esquerda ele mostra o breadcrumb do arquivo ativo, por exemplo `proj > src > file.pbs`.
Na direita ele mostra:
1. posicao atual em `L:C`;
2. line separator;
3. modo de tabs/espacos, por exemplo `Spaces: 2` ou `Spaces: 4`;
4. extensao ou linguagem do arquivo ativo;
5. um cadeado de `read-only` apenas visual, reservado para funcionalidade futura do editor, sem efeito nesta wave.
Como a primeira wave e read-only, ela nao fecha agora dirty tracking, save ou merge entre buffer local e disco.
O comportamento minimo fica reduzido a:
1. abrir arquivos em memoria para leitura;
2. atualizar a visao a partir de refresh manual e refresh inicial;
3. deixar escrita, dirty state e resolucao de conflitos para wave posterior.
Tambem nao vale persistir estado de sessao agora.
Expansao da arvore, tabs abertas e qualquer outro estado visual vivem apenas na sessao atual; persistencia entre execucoes fica para depois.
Nao vale a pena transformar esta agenda em contrato detalhado de eventos agora.
Se algum evento precisar aparecer durante implementacao, ele deve entrar apenas como comentario/local detail e nao como fechamento normativo desta discussion.
## Resolution
@@ -167,12 +225,22 @@ Recommended direction: seguir com **Option B**.
A agenda deve convergir para uma decisao com os seguintes fechamentos:
1. o Studio deve possuir uma camada generica de `document/session` para o Code Editor;
2. essa camada pode ler e escrever arquivos fonte e manter snapshots documentais em memoria;
3. essa camada nao deve possuir semantica de linguagem, parsing autoritativo ou diagnosticos como responsabilidade primaria;
4. frontends devem consumir snapshots documentais do editor por um contrato explicito, imutavel e versionado;
5. como o compiler hoje ainda le do filesystem, a decisao precisa fechar uma etapa/seam concreta para injetar `document snapshots` antes do pipeline, uniformizando a entrada de Studio, FE services e LSP futuro;
6. LSP fica explicitamente fora do primeiro wave, mas a modelagem precisa deixar caminho limpo para ele;
7. a primeira wave do editor deve normatizar explicitamente o baseline visual do workspace: `Project Navigator` na esquerda, tabs no topo da area central, editor rico no corpo e `Editor Helper Panel` inferior reservado;
8. o `Editor Helper Panel` nasce passivo na primeira wave, como espaco reservado para prompts, tips e feedback contextual, sem obrigar interatividade imediata.
2. essa camada deve operar em modo read-only nesta primeira wave, podendo abrir arquivos fonte e manter snapshots documentais em memoria apenas para leitura;
3. essa camada deve ser responsavel por organizacao de componentes, tabs, buffers abertos, refresh/reload e snapshot estrutural do projeto, sem dirty tracking, save ou merge local nesta wave;
4. essa camada nao deve possuir semantica de linguagem, parsing autoritativo, diagnosticos ou ownership de comportamento tipico de LSP;
5. a primeira wave deve reservar um seam explicito para provedores semanticos futuros, incluindo LSP, sem torna-los dependencia imediata e sem endurecer o editor contra eles;
6. a primeira wave do editor deve normatizar explicitamente o baseline visual do workspace: `Project Navigator` na esquerda, tabs no topo da area central, editor rico no corpo, `Editor Helper Panel` inferior reservado e `status bar` passivo;
7. a coluna esquerda deve reservar uma regiao de `Outline` abaixo do `Project Navigator`, mas sem comportamento funcional nesta wave;
8. o `Project Navigator` deve mostrar todos os arquivos e diretorios do projeto, incluindo arquivos ocultos por padrao, ordenando pastas antes de arquivos em ordem alfabetica e usando `prometeu.json` apenas para taggear corretamente roots/fontes relevantes ao frontend selecionado;
9. o `Project Navigator` deve manter um snapshot estrutural em memoria da arvore do projeto para navegacao e estado visual, sem substituir o filesystem como source of truth;
10. a arvore do projeto deve fazer refresh inicial ao abrir o projeto e permitir refresh manual a qualquer momento por um botao proprio no `Project Navigator`;
11. snapshots de conteudo em memoria ficam restritos aos arquivos abertos no editor;
12. arquivos nao-textuais ou nao suportados podem aparecer no navigator, mas devem abrir um modal simples avisando que o arquivo nao e suportado nesta wave;
13. a primeira wave de tabs deve abrir todo arquivo novo em nova tab, usar uma faixa responsiva com overflow no estilo IntelliJ, manter a tab ativa visivel e usar apenas o nome do arquivo com extensao como rotulo da tab;
14. o `status bar` deve mostrar breadcrumb do arquivo ativo na esquerda e, na direita, `L:C`, line separator, modo de tabs/espacos, extensao/linguagem e um cadeado visual de `read-only` sem efeito funcional ainda; `L:C` pode nascer como placeholder visual nesta wave;
15. o `Editor Helper Panel` nasce passivo na primeira wave apenas para demarcar espaco, sem funcao real ainda;
16. expansao da arvore, tabs abertas e demais estados visuais vivem apenas na sessao atual; persistencia entre execucoes fica para depois;
17. ficam explicitamente fora desta wave escrita, save, dirty tracking, merge de conflitos, autocomplete, go to definition, semantic diagnostics ao digitar, symbols, rename, code actions e qualquer decisao detalhada de integracao com LSP;
18. esta agenda nao fecha agora um contrato normativo de eventos editoriais; qualquer necessidade imediata pode aparecer apenas como detalhe de implementacao ou comentario.
Next step suggestion: converter esta agenda em uma `decision` que feche o boundary entre `EditorWorkspace`, sessao documental do Studio e servicos de frontend, incluindo o escopo exato da primeira wave de UI sem LSP.
Next step suggestion: converter esta agenda em uma `decision` que feche o escopo da primeira wave read-only do `EditorWorkspace`, incluindo composicao visual, tabs, `Project Navigator`, `status bar`, snapshot estrutural da arvore, buffers abertos em memoria e o que fica explicitamente fora da wave por ausencia de escrita/semantica/LSP.