prometeu-studio/discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md

---
id: AGD-0015
ticket: studio-frontend-owned-semantic-editor-presentation
title: Definir ownership do schema visual semantico do editor por frontend
status: accepted
created: 2026-04-02
resolved: 2026-04-02
decision: DEC-0012
tags:
  - studio
  - editor
  - frontend
  - presentation
  - semantic-highlighting
  - compiler
  - pbs
---

## Pain

Hoje o Code Editor do Studio aplica um schema visual generico de frontend em `prometeu-studio/src/main/resources/themes/editor/presentations/fe.css`.

Isso resolve a primeira wave de consumo semantico, mas deixa a responsabilidade errada:

- o Studio hospeda o renderer;
- o LSP/FE emite chaves semanticas;
- mas a cor final fica centralizada num tema generico do Studio;
- e a linguagem concreta perde ownership editorial sobre sua propria aparencia semantica.

Na pratica, isso significa que PBS esta sendo colorido por um tema global de `FE`, mesmo sendo a propria FE que sabe quais categorias devem existir, quais cores fazem sentido e como essa linguagem quer ser lida.

## Context

Domain owner: `studio`
Owner surface: `discussion/...` agora; futuras propagacoes normativas devem atingir `docs/specs/studio` e, se necessario, specs do dominio `compiler/<language>`.

Superficies e referencias relevantes:

- `DEC-0011` aceitou a fase minima de FE read-only com diagnostics, symbols, definition e highlight no editor;
- o Studio hoje resolve qualquer frontend para uma presentation unica `fe` em `EditorDocumentPresentationRegistry`;
- o tema visual semantico dessa presentation esta em `prometeu-studio/src/main/resources/themes/editor/presentations/fe.css`;
- as semantic keys atuais sao emitidas pelo LSP em `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`;
- PBS e hoje a unica FE integrada ao Studio, mas o desenho do editor foi aberto como multi-frontend desde as foundations do workspace;
- `studio` deve continuar owner da superficie de renderizacao do editor, mas isso nao implica ownership do schema visual normativo de cada linguagem.

Clarificacoes importantes:

- esta agenda nao discute edit rights de FE;
- esta agenda nao rediscute `DEC-0011`;
- esta agenda trata de ownership editorial e contrato de presentation para highlight semantico no editor;
- o owner principal do workflow continua `studio`, com referencia explicita ao dominio `compiler/<language>` para assets ou contratos language-owned.

## Open Questions

- [x] O schema visual semantico de uma linguagem deve ser owner da FE especifica em vez de um tema generico do Studio.
- [x] O Studio nao deve ser owner de stylesheet semantico de FE; ele deve apenas consumir o contrato resolvido pelo hub LSP.
- [x] O LSP tambem nao deve ser owner de recursos da FE; ele deve agir como hub/contrato entre FE e Studio.
- [x] Cada FE deve publicar sua propria semantica e seu proprio CSS de highlight acompanhando a FE.
- [x] O LSP nao deve reduzir a semantica da FE para um set comum artificial como `fe-keyword`, `fe-type` ou equivalentes.
- [x] Nao deve haver fallback visual generico; se a FE nao publicar, ou se nao houver recurso usavel, o Studio simplesmente nao aplica semantic highlight.
- [x] A FE deve produzir semantic keys a partir de um vocabulário semântico language-owned, por exemplo `PbsSemanticKind`, usando `semanticKey` como forma contratual estavel e nao algo presentation-owned como `cssKey`.
- [x] O casamento entre semantic key e CSS acontece no Studio apenas como projecao mecanica de classe, sem traducao semantica intermediaria.
- [x] O hub LSP deve expor esse contrato para o Studio por meio de um descriptor proprio, produzido a partir do `FrontendSpec` vindo da analise.
- [x] O shape inicial desse descriptor deve permanecer completo, mas simples: semantic keys + resources, ambos dentro de uma mesma mensagem/descriptor para facilitar evolucao futura.
- [x] O Studio nao deve fazer validacao profunda do contrato; aceita o que houver e, se nao houver contract/resource usavel, simplesmente nao destaca semanticamente.
- [x] Nao deve existir erro de contrato exposto no Studio; no maximo, log comum de desenvolvimento.
- [x] Os assets da FE devem viver em `resources/` e ser resolvidos como qualquer outro resource Java.
- [x] O contrato deve viver no `FrontendSpec`, que continua como superficie estatica.
- [x] A presenca e consistencia minima desse contrato no `FrontendSpec` podem ser validadas por testes da propria FE.
- [x] Se semantic keys ou resources estiverem ausentes em runtime, o Studio segue sem highlight em vez de falhar.

## Options

### Option A - Manter schema visual generico de FE no Studio
- **Approach:** Continuar com `fe.css` como presentation unica para qualquer linguagem frontend, mantendo o Studio como owner das cores e aceitando uma taxonomia reduzida comum.
- **Pro:** Implementacao simples e baixo churn imediato.
- **Con:** A FE continua sem ownership sobre sua propria apresentacao semantica e o Studio acumula regra editorial que nao lhe pertence.
- **Maintainability:** Fraca. Escala mal quando houver mais de uma linguagem.

### Option B - FE publica semantica e presentation proprias, LSP atua como hub contratual
- **Approach:** Cada frontend publica sua taxonomia semantica real e seus resources de presentation proprios; a semantic key nasce de um vocabulário language-owned da FE; o contrato vive de forma estatica no `FrontendSpec`; o LSP produz, a partir do `FrontendSpec` resolvido na analise, um descriptor proprio com semantic keys + resources e expõe isso ao Studio sem reduzir a linguagem a um set comum artificial e sem capturar ownership de recursos.
- **Pro:** Ownership correto, melhor escalabilidade multi-frontend e capacidade de cada linguagem definir sua propria identidade visual e suas categorias.
- **Con:** Exige um contrato novo e mais explicito entre FE, LSP e Studio.
- **Maintainability:** Forte. Separa host UI de schema semanticamente owner-driven.

### Option C - Studio continua owner do CSS, mas por frontend especifico
- **Approach:** O Studio deixa de ter um unico `fe.css` e passa a manter `pbs.css`, `foo.css`, etc., ainda sob ownership do modulo Studio.
- **Pro:** Melhora a diferenciacao por linguagem com mudanca tecnica pequena.
- **Con:** Corrige o sintoma, nao a fronteira de ownership. O Studio continuaria decidindo visual de linguagem.
- **Maintainability:** Media. Menos acoplado que hoje, mas ainda ownership errado.

## Discussion

O problema real aqui nao e "qual azul usar para keyword".
O problema e quem e responsavel por declarar a semantica e o schema visual de uma categoria semantica.

Hoje, o pipeline esta dividido assim:

- a FE/LSP identifica categorias semanticas;
- o Studio renderiza spans;
- o tema final vem de um CSS generico de frontend.

Isso foi um atalho razoavel para a primeira fase, mas entra em conflito com o desenho multi-frontend do editor.
Se mais uma linguagem entrar, o `fe.css` inevitavelmente vira:

- denominador comum fraco;
- ou lugar de negociacao editorial entre linguagens;
- ou conjunto de excecoes por linguagem escondidas num host que nao deveria ser owner disso.

Option C parece tentadora porque reduz impacto tecnico:

- sair de `fe.css` para `pbs.css`;
- manter o Studio resolvendo presentation por tipo;
- e encerrar o assunto.

Mas isso nao fecha a questao conceitual.
Ainda seria o Studio definindo a paleta normativa da FE.
O acoplamento mudaria de "frontend generico" para "frontend por linguagem, mas ainda host-owned".

O recorte que voce fechou agora deixa a fronteira desejada bem mais objetiva:

- cada FE deve publicar sua propria semantica;
- cada FE deve publicar o CSS proprio que sabe highlightar essa semantica;
- cada FE deve gerar semantic keys a partir de um vocabulário semântico próprio e estável;
- o LSP deve agir como hub/contrato que liga metadados e presentation da FE ao Studio e vice-versa;
- o Studio nao deve ser owner de nenhum recurso da FE;
- o LSP tambem nao deve ser owner de nenhum recurso da FE.

Tambem ficou explicitamente rejeitada a ideia de o LSP reduzir a FE a um vocabulário comum artificial como `fe-keyword`, `fe-type`, `fe-callable` e semelhantes.
Esse tipo de normalizacao achataria a linguagem e recolocaria ownership semantico no lugar errado.
O LSP deve transportar o contrato da FE, nao reinterpretar a FE em um dialeto comum do Studio.

Option B parece a direcao correta porque preserva as fronteiras certas:

- o Studio continua dono do editor, layout, interacao, status bar, warning surfaces e plumbing de style application;
- a FE passa a publicar a semantica e a presentation semantica que lhe pertencem;
- o LSP vira a ponte contratual entre FE e Studio, sem capturar ownership do asset;
- a ausencia de presentation propria nao gera fallback generico; apenas desliga semantic highlight.

Tambem importa decidir o nivel do contrato.
Ha pelo menos duas camadas diferentes:

1. taxonomia semantica
- quais chaves existem e como a FE as nomeia
- essa camada agora passa a ser explicitamente language-owned
- o hub LSP nao deve colapsar essas chaves em um set comum artificial
- a forma contratual recomendada para cada item e `semanticKey`, nao `cssKey`, porque a mesma chave pode servir a mais de um consumer

2. presentation
- como essas chaves sao coloridas/estilizadas
- essa camada tambem passa a ser explicitamente language-owned
- o CSS consome semantic keys declaradas pela FE; ele nao define o vocabulário semanticamente owner

O que permanece em aberto nao e mais o ownership.
O ownership ficou claro.
O shape do contrato tambem ficou suficientemente delineado:

- deve existir um descriptor proprio;
- esse descriptor deve ser produzido a partir do `FrontendSpec` resolvido durante a analise;
- o contrato fonte continua vivendo no `FrontendSpec`, que permanece estatico;
- o shape inicial deve ser simples: semantic keys + resources;
- semantic keys e resources devem estar juntos em uma unica mensagem/descriptor para facilitar evolucao futura;
- os resources devem viver junto da FE em `resources/`;
- o Studio consome o descriptor e tenta carregar o que existir;
- se nao houver descriptor ou resource usavel, simplesmente nao aplica highlight.

A ligacao entre semantica concreta e stylesheet tambem ficou melhor definida:

- a FE classifica semanticamente seus elementos usando um vocabulário proprio, por exemplo `PbsSemanticKind`;
- cada `SemanticKind` da FE deve expor uma `semanticKey` estavel;
- o LSP transporta essa `semanticKey` como parte do highlight semantico;
- o Studio nao traduz a key para outro dialeto semantico;
- o Studio apenas projeta a key para uma classe CSS por regra mecanica;
- o CSS publicado pela FE estiliza essa classe correspondente.

Exemplo de direcao:

- `PbsSemanticKind.FUNCTION -> semanticKey = "pbs-function"`
- o LSP envia `"pbs-function"`
- o Studio projeta para uma classe como `editor-semantic-pbs-function`
- o CSS da FE PBS define essa classe

Tambem ficou claro onde esse material vive fisicamente:

- o asset deve acompanhar a FE;
- o lugar natural e `resources/` da propria FE;
- a resolucao deve seguir o fluxo normal de resources Java;
- o Studio nao precisa inventar loader especial fora dessa convencao.

A estrategia de robustez tambem ficou fechada:

- o `FrontendSpec` pode e deve ser coberto por testes da FE para garantir a presenca minima desse contrato;
- isso permite detectar omissoes cedo sem transformar o Studio em validador pesado;
- em runtime, ausencia de semantic keys, resources ou casamento suficiente nao bloqueia o editor;
- o comportamento final continua sendo degradar para "sem highlight".

## Resolution

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

Direcao recomendada neste momento:

1. o schema visual semantico nao deve permanecer como responsabilidade generica do Studio;
2. cada FE deve publicar sua propria semantica;
3. cada FE deve publicar seu proprio CSS de highlight acompanhando a FE;
4. o LSP deve atuar como hub/contrato entre FE e Studio, expondo os metadados necessarios para o editor sem reduzir a linguagem a um set comum artificial;
5. as semantic keys devem nascer de vocabulário language-owned da FE, por exemplo `SemanticKind -> semanticKey`;
6. o Studio deve continuar apenas como host do renderer e consumidor desse contrato;
7. o casamento entre semantic key e CSS deve acontecer no Studio apenas como projecao mecanica de classe, sem traducao semantica intermediaria;
8. nem Studio nem LSP devem ser owners de qualquer recurso da FE;
9. o contrato de semantic presentation deve viver no `FrontendSpec`, que permanece uma superficie estatica;
10. o LSP deve expor ao Studio um descriptor proprio de semantic presentation, produzido a partir do `FrontendSpec` resolvido na analise;
11. o shape inicial desse descriptor deve permanecer simples: semantic keys + resources;
12. semantic keys e resources devem fazer parte de uma unica mensagem/descriptor para facilitar evolucao futura;
13. os assets da FE devem viver em `resources/` da propria FE e ser resolvidos como qualquer outro resource Java;
14. o `FrontendSpec` e esse contrato podem ser cobertos por testes da propria FE;
15. o Studio nao deve fazer validacao profunda desse contrato; se houver descriptor e resource usavel, aplica highlight; se nao houver, nao aplica;
16. nao deve existir fallback generico que substitua a presentation da FE por um schema comum do host;
17. falhas nessa publicacao nao devem virar erro de UI no Studio; no maximo, log comum de desenvolvimento;
18. a agenda esta convertida em `DEC-0012`;
19. a propagacao futura provavelmente toca `docs/specs/studio` e tambem superfícies normativas do dominio `compiler/<language>`.

Next step suggestion: converter esta agenda em `decision` normativa sobre ownership da presentation semantica por FE, fechando o descriptor produzido a partir de `FrontendSpec` e o comportamento "sem contract/resource -> sem highlight".