--- 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/`. 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/` 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/`. 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".