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

id	ticket	title	status	created	resolved	decision	tags
AGD-0015	studio-frontend-owned-semantic-editor-presentation	Definir ownership do schema visual semantico do editor por frontend	accepted	2026-04-02	2026-04-02	DEC-0012	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

• O schema visual semantico de uma linguagem deve ser owner da FE especifica em vez de um tema generico do Studio.
• O Studio nao deve ser owner de stylesheet semantico de FE; ele deve apenas consumir o contrato resolvido pelo hub LSP.
• O LSP tambem nao deve ser owner de recursos da FE; ele deve agir como hub/contrato entre FE e Studio.
• Cada FE deve publicar sua propria semantica e seu proprio CSS de highlight acompanhando a FE.
• O LSP nao deve reduzir a semantica da FE para um set comum artificial como fe-keyword, fe-type ou equivalentes.
• Nao deve haver fallback visual generico; se a FE nao publicar, ou se nao houver recurso usavel, o Studio simplesmente nao aplica semantic highlight.
• 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.
• O casamento entre semantic key e CSS acontece no Studio apenas como projecao mecanica de classe, sem traducao semantica intermediaria.
• O hub LSP deve expor esse contrato para o Studio por meio de um descriptor proprio, produzido a partir do FrontendSpec vindo da analise.
• O shape inicial desse descriptor deve permanecer completo, mas simples: semantic keys + resources, ambos dentro de uma mesma mensagem/descriptor para facilitar evolucao futura.
• O Studio nao deve fazer validacao profunda do contrato; aceita o que houver e, se nao houver contract/resource usavel, simplesmente nao destaca semanticamente.
• Nao deve existir erro de contrato exposto no Studio; no maximo, log comum de desenvolvimento.
• Os assets da FE devem viver em resources/ e ser resolvidos como qualquer outro resource Java.
• O contrato deve viver no FrontendSpec, que continua como superficie estatica.
• A presenca e consistencia minima desse contrato no FrontendSpec podem ser validadas por testes da propria FE.
• 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".