FE highlight ownership

discussion/index.ndjson

@@ -1,4 +1,4 @@
-{"type":"meta","next_id":{"DSC":14,"AGD":15,"DEC":12,"PLN":26,"LSN":28,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":14,"AGD":15,"DEC":13,"PLN":29,"LSN":28,"CLSN":1}}
 {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
 {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
@@ -12,3 +12,4 @@
 {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
 {"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
 {"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0010","file":"DEC-0010-studio-controlled-non-frontend-editor-write-wave.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0013"},{"id":"DEC-0011","file":"DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0014"}],"plans":[{"id":"PLN-0019","file":"PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0020","file":"PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0021","file":"PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0022","file":"PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0023","file":"PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0024","file":"PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0025","file":"PLN-0025-implement-fe-semantic-highlight-consumption.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0014","status":"open","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[{"id":"AGD-0015","file":"AGD-0015-studio-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-frontend-owned-semantic-editor-presentation.md","status":"accepted","created_at":"2026-04-02","updated_at":"2026-04-02","ref_agenda":"AGD-0015"}],"plans":[{"id":"PLN-0026","file":"PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0027","file":"PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]},{"id":"PLN-0028","file":"PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md","status":"review","created_at":"2026-04-02","updated_at":"2026-04-02","ref_decisions":["DEC-0012"]}],"lessons":[]}

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

@@ -0,0 +1,223 @@
+---
+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".

discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md

@@ -0,0 +1,142 @@
+---
+id: DEC-0012
+ticket: studio-frontend-owned-semantic-editor-presentation
+title: Frontend-owned semantic editor presentation via FrontendSpec-derived descriptor
+status: accepted
+created: 2026-04-02
+accepted: 2026-04-02
+agenda: AGD-0015
+plans:
+  - PLN-0026
+  - PLN-0027
+  - PLN-0028
+tags:
+  - studio
+  - editor
+  - frontend
+  - presentation
+  - semantic-highlighting
+  - compiler
+  - pbs
+---
+
+## Decision
+
+The semantic editor presentation for frontend documents SHALL be frontend-owned.
+
+Normative decision:
+
+1. Each frontend MUST publish its own semantic vocabulary.
+2. Each frontend MUST publish its own semantic highlight resources.
+3. Neither Studio nor LSP SHALL own frontend semantic presentation assets.
+4. The canonical source of this contract MUST live in `FrontendSpec`.
+5. LSP MUST act only as a hub/contract bridge between frontend metadata and Studio consumption.
+6. LSP MUST NOT reduce frontend semantics into a shared artificial vocabulary such as `fe-keyword`, `fe-type`, or equivalent host-owned categories.
+7. Studio MUST consume the frontend semantic presentation contract without reinterpreting frontend semantics.
+8. Studio MUST project semantic keys to CSS classes mechanically, without semantic translation tables.
+9. If semantic presentation metadata or usable resources are absent at runtime, Studio SHALL not apply semantic highlight for that frontend document.
+10. Studio MUST NOT replace missing frontend presentation with a generic host-owned fallback theme.
+
+## Rationale
+
+The prior arrangement centralized frontend semantic colors in Studio under a generic `fe.css` presentation. That arrangement was acceptable as an early integration shortcut, but it violates the intended boundary of a multi-frontend editor:
+
+- Studio owns rendering surfaces and editor UX.
+- The frontend owns semantic meaning.
+- Semantic presentation is part of that frontend-owned meaning.
+
+If Studio remains the owner of semantic presentation, every additional frontend either:
+
+- collapses into a weak common denominator,
+- negotiates language-specific editorial rules inside the host,
+- or forces Studio to accumulate language-owned semantics.
+
+That is the wrong ownership direction.
+
+LSP is also not the correct owner. Its role in this design is to bridge frontend analysis products into host consumption, not to normalize, reinterpret, or host language assets.
+
+This decision therefore locks the boundary as follows:
+
+- frontend owns semantic vocabulary,
+- frontend owns semantic presentation assets,
+- `FrontendSpec` is the canonical contract source,
+- LSP derives and transports a consumable descriptor,
+- Studio renders what the frontend publishes.
+
+## Technical Specification
+
+### 1. Canonical Contract Source
+
+1. `FrontendSpec` MUST carry the semantic presentation contract.
+2. `FrontendSpec` SHALL remain a static specification surface.
+3. The semantic presentation contract MUST be frontend-owned and versionable together with the frontend.
+
+### 2. Contract Shape
+
+The initial semantic presentation contract MUST remain simple but complete.
+
+It SHALL include, at minimum:
+
+1. `semanticKeys`
+2. `resources`
+
+These fields MUST be carried inside a single descriptor/message so the contract can evolve without scattering related presentation metadata across multiple unrelated surfaces.
+
+At minimum:
+
+- `semanticKeys` defines the frontend-owned stable semantic keys consumable by the editor pipeline.
+- `resources` defines the frontend-owned presentation resources, including the stylesheet resource used for semantic highlight.
+
+### 3. Frontend Semantic Vocabulary
+
+1. Semantic keys MUST be produced from a frontend-owned semantic vocabulary, for example `SemanticKind -> semanticKey`.
+2. A semantic key MUST be stable enough to serve as contract output.
+3. The name of this contract field SHOULD be `semanticKey`, not `cssKey`, because the key is not owned by CSS and may serve multiple consumers.
+
+### 4. LSP Responsibility
+
+1. LSP MUST derive a semantic presentation descriptor from the `FrontendSpec` resolved during analysis.
+2. LSP MUST expose that descriptor to Studio.
+3. LSP MUST NOT translate frontend semantic keys into host-owned generic categories.
+4. LSP MUST NOT become the owner of frontend stylesheets or semantic resources.
+
+### 5. Studio Responsibility
+
+1. Studio MUST remain the owner of rendering, style application, and editor UI plumbing.
+2. Studio MUST NOT define frontend semantic vocabulary.
+3. Studio MUST map semantic keys into CSS classes mechanically.
+4. That mapping MUST be syntactic only, not semantic.
+
+Illustrative direction:
+
+- frontend semantic key: `pbs-function`
+- Studio-applied class: `editor-semantic-pbs-function`
+
+The exact class projection convention MAY be specified later, but the projection MUST remain mechanical and MUST NOT introduce host-owned semantic translation.
+
+### 6. Resource Ownership and Resolution
+
+1. Frontend semantic presentation resources MUST live under the frontend's own `resources/` surface.
+2. These resources MUST be resolved like ordinary Java resources.
+3. Studio and LSP MUST consume these resources through the contract and MUST NOT duplicate or host them as owners.
+
+### 7. Validation and Runtime Behavior
+
+1. Deep runtime validation in Studio is NOT required.
+2. Frontend teams SHOULD cover semantic presentation publication with frontend tests.
+3. If descriptor data is present and resources are usable, Studio SHOULD apply semantic highlight.
+4. If descriptor data is absent or resources are unusable, Studio SHALL continue without semantic highlight.
+5. This condition MUST NOT surface as a product-facing Studio error.
+6. At most, normal development logs MAY record the condition.
+
+## Constraints
+
+1. This decision does NOT change FE edit rights.
+2. This decision does NOT revise `DEC-0011`; it refines ownership and contract shape for semantic presentation only.
+3. This decision MUST NOT be implemented by reintroducing a generic host-owned `fe.css` fallback.
+4. This decision MUST NOT be implemented by collapsing language semantics into generic host-owned semantic buckets.
+5. Any future expansion of the descriptor MUST preserve frontend ownership and the single-descriptor principle established here.
+
+## Revision Log
+
+- 2026-04-02: Initial accepted decision from AGD-0015.

discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md

@@ -0,0 +1,113 @@
+---
+id: PLN-0026
+ticket: studio-frontend-owned-semantic-editor-presentation
+title: Propagate DEC-0012 into Studio and frontend normative specs
+status: review
+created: 2026-04-02
+completed:
+tags:
+  - studio
+  - editor
+  - frontend
+  - specs
+  - semantic-highlighting
+---
+
+## Objective
+
+Propagate `DEC-0012` into the normative documentation surfaces that define semantic editor presentation ownership, contract source, and runtime fallback behavior.
+
+## Background
+
+`DEC-0012` locks a new ownership model:
+
+- frontend owns semantic vocabulary;
+- frontend owns semantic presentation resources;
+- `FrontendSpec` is the canonical source of the semantic presentation contract;
+- LSP derives a descriptor from `FrontendSpec`;
+- Studio consumes the descriptor without semantic reinterpretation;
+- missing descriptor or resources degrade to no semantic highlight.
+
+These rules must be reflected in the Studio and frontend-facing specs before implementation work proceeds.
+
+## Scope
+
+### Included
+- Studio editor specification updates for frontend-owned semantic presentation.
+- LSP semantic read phase specification updates for descriptor bridging behavior.
+- Compiler/frontend specification updates that place semantic presentation contract ownership in `FrontendSpec`.
+- Documentation of the runtime behavior `no contract/resource -> no highlight`.
+
+### Excluded
+- Java implementation changes.
+- FE resource creation or stylesheet migration.
+- Test implementation.
+
+## Execution Steps
+
+### Step 1 - Update Studio semantic editor ownership rules
+
+**What:**
+Update Studio specs so the editor is no longer the owner of a generic frontend semantic theme.
+
+**How:**
+Amend the Code Editor and related Studio specs to state that Studio hosts rendering only, consumes a frontend-owned descriptor, and applies no generic fallback theme.
+
+**File(s):**
+- `docs/specs/studio/5. Code Editor Workspace Specification.md`
+- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
+
+### Step 2 - Update frontend contract ownership rules
+
+**What:**
+Document that frontend semantic presentation contract data lives in `FrontendSpec`.
+
+**How:**
+Amend compiler/frontend spec surfaces to describe `semanticKeys + resources` as frontend-owned static contract data published through `FrontendSpec`.
+
+**File(s):**
+- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
+- `docs/specs/compiler-languages/pbs/README.md`
+- any more specific frontend spec file that currently owns frontend metadata publication semantics
+
+### Step 3 - Lock runtime degradation behavior in spec text
+
+**What:**
+Specify the runtime behavior when semantic presentation contract data or resources are absent.
+
+**How:**
+State normatively that Studio must continue without semantic highlight, must not surface a product-facing UI error, and may only emit normal development logs.
+
+**File(s):**
+- `docs/specs/studio/5. Code Editor Workspace Specification.md`
+- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
+
+## Test Requirements
+
+### Unit Tests
+- No code tests in this plan.
+
+### Integration Tests
+- No runtime tests in this plan.
+
+### Manual Verification
+- Review updated spec text against every normative clause in `DEC-0012`.
+- Verify no spec reintroduces a Studio-owned generic frontend theme.
+
+## Acceptance Criteria
+
+- [ ] Studio specs state that semantic presentation is frontend-owned.
+- [ ] Specs name `FrontendSpec` as the canonical contract source.
+- [ ] Specs describe the descriptor shape at a high level as `semanticKeys + resources`.
+- [ ] Specs define `no contract/resource -> no highlight`.
+- [ ] Specs define that no generic Studio fallback theme is allowed.
+
+## Dependencies
+
+- Depends on `DEC-0012`.
+- Should complete before or in parallel with implementation plans so implementation follows normative text.
+
+## Risks
+
+- Existing spec text may still imply Studio ownership of generic frontend presentation.
+- Compiler spec propagation may be underspecified if the exact frontend metadata sections are spread across multiple files.

discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md

@@ -0,0 +1,139 @@
+---
+id: PLN-0027
+ticket: studio-frontend-owned-semantic-editor-presentation
+title: Add frontend semantic presentation contract to FrontendSpec and expose it through LSP
+status: review
+created: 2026-04-02
+completed:
+tags:
+  - compiler
+  - frontend
+  - lsp
+  - contract
+  - semantic-highlighting
+---
+
+## Objective
+
+Implement the frontend-owned semantic presentation contract in `FrontendSpec` and expose a derived descriptor through LSP without collapsing frontend semantics into host-owned categories.
+
+## Background
+
+`DEC-0012` requires:
+
+- static contract data in `FrontendSpec`;
+- a simple descriptor containing `semanticKeys + resources`;
+- frontend-owned semantic vocabulary using stable `semanticKey` values;
+- LSP as a hub that derives and exposes the descriptor to Studio;
+- no generic semantic-key reduction such as `fe-keyword`.
+
+## Scope
+
+### Included
+- `FrontendSpec` contract model additions.
+- FE-specific publication of semantic keys and semantic presentation resources.
+- Replacement of generic LSP semantic key emission with frontend-owned keys.
+- LSP descriptor derivation and API exposure.
+- FE-side tests covering contract presence and consistency.
+
+### Excluded
+- Studio CSS application changes.
+- Studio presentation registry migration.
+- Removal of legacy Studio stylesheets, except where required to avoid compile/runtime conflicts.
+
+## Execution Steps
+
+### Step 1 - Extend FrontendSpec with semantic presentation contract
+
+**What:**
+Add a static semantic presentation contract to `FrontendSpec`.
+
+**How:**
+Introduce a dedicated descriptor type that carries frontend-owned `semanticKeys + resources`, wire it into `FrontendSpec`, and keep `FrontendSpec` static and frontend-owned.
+
+**File(s):**
+- `prometeu-compiler/prometeu-frontend-api/src/main/java/.../FrontendSpec.java`
+- any adjacent model files needed for the new descriptor type
+
+### Step 2 - Publish PBS semantic vocabulary and resources through FrontendSpec
+
+**What:**
+Make PBS publish frontend-owned semantic keys and highlight resources.
+
+**How:**
+Add a frontend-owned semantic vocabulary model such as `PbsSemanticKind -> semanticKey`, publish the resulting semantic presentation contract from PBS frontend definitions, and point the descriptor to FE-owned resources.
+
+**File(s):**
+- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java`
+- PBS semantic analysis/indexing files that currently assign generic `fe-*` categories
+- FE resource directory under the PBS frontend module
+
+### Step 3 - Remove generic semantic key collapse in LSP
+
+**What:**
+Stop translating frontend semantics into host-owned generic semantic keys.
+
+**How:**
+Replace `fe-keyword`, `fe-type`, and similar outputs with frontend-owned semantic keys coming from frontend semantic vocabulary and/or `FrontendSpec` contract data.
+
+**File(s):**
+- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
+- any LSP DTO/message models that need to surface the descriptor
+
+### Step 4 - Expose descriptor from analysis to Studio-facing LSP results
+
+**What:**
+Expose a Studio-consumable descriptor derived from the resolved `FrontendSpec`.
+
+**How:**
+Derive the descriptor during analysis/session creation and include it in the LSP surface that Studio consumes for semantic highlight application.
+
+**File(s):**
+- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
+- `prometeu-lsp/prometeu-lsp-api/src/main/java/...` messages/DTOs
+- any semantic session models involved in transport
+
+### Step 5 - Add FE contract tests
+
+**What:**
+Verify the FE contract is present and coherent.
+
+**How:**
+Add frontend tests that fail when semantic presentation contract data is missing, when semantic keys are not published, or when published resources do not match the FE contract shape expectations.
+
+**File(s):**
+- PBS frontend tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...`
+- frontend-api tests if `FrontendSpec` invariants are enforced there
+
+## Test Requirements
+
+### Unit Tests
+- `FrontendSpec` tests for semantic presentation descriptor presence and shape.
+- PBS frontend tests for semantic key publication.
+- LSP tests for transport of frontend-owned semantic keys and descriptor data.
+
+### Integration Tests
+- Analyze a PBS file through LSP and assert that returned semantic highlights use PBS-owned semantic keys.
+- Assert that the descriptor surfaced to the consumer contains the expected `semanticKeys + resources`.
+
+### Manual Verification
+- Inspect LSP payloads/logs to confirm there is no remaining `fe-*` semantic key collapse for PBS.
+
+## Acceptance Criteria
+
+- [ ] `FrontendSpec` exposes a static semantic presentation contract.
+- [ ] PBS publishes semantic keys and resources through that contract.
+- [ ] LSP no longer emits generic host-owned semantic keys for PBS.
+- [ ] LSP exposes a descriptor derived from resolved `FrontendSpec`.
+- [ ] FE tests cover missing contract data and contract consistency.
+
+## Dependencies
+
+- Depends on `DEC-0012`.
+- Should land before Studio consumption changes in `PLN-0028`.
+
+## Risks
+
+- Existing semantic indexing code is currently host-owned and may require a larger refactor than expected.
+- DTO surface changes can ripple through Studio and tests.
+- Resource publication conventions may be inconsistent across future frontends if not modeled cleanly now.

discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md

@@ -0,0 +1,132 @@
+---
+id: PLN-0028
+ticket: studio-frontend-owned-semantic-editor-presentation
+title: Consume frontend-owned semantic presentation in Studio and retire generic FE theme usage
+status: review
+created: 2026-04-02
+completed:
+tags:
+  - studio
+  - editor
+  - semantic-highlighting
+  - frontend
+  - presentation
+---
+
+## Objective
+
+Make Studio consume the frontend-owned semantic presentation descriptor from LSP, apply FE-owned resources, and degrade cleanly to no highlight when semantic presentation data is unavailable.
+
+## Background
+
+`DEC-0012` and `PLN-0027` move semantic presentation ownership out of Studio. After the descriptor and frontend resources exist, Studio must stop relying on generic frontend presentation styling and instead consume FE-owned semantic presentation data.
+
+## Scope
+
+### Included
+- Studio-side consumption of the LSP semantic presentation descriptor.
+- Mechanical semantic key to CSS class projection.
+- Loading FE-owned highlight resources through normal Java resource resolution.
+- Graceful no-highlight behavior when descriptor/resources are unavailable.
+- Removal of generic FE-specific highlight ownership assumptions from Studio runtime flow.
+
+### Excluded
+- Frontend contract creation.
+- LSP descriptor creation.
+- Spec writing.
+
+## Execution Steps
+
+### Step 1 - Add descriptor-aware Studio highlight consumption
+
+**What:**
+Teach Studio editor highlighting flow to consume the frontend semantic presentation descriptor.
+
+**How:**
+Extend the Studio-side LSP consumption path so semantic highlight application depends on descriptor data and no longer assumes a single generic frontend presentation.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`
+
+### Step 2 - Replace generic FE styling assumption with mechanical class projection
+
+**What:**
+Project frontend semantic keys directly into CSS classes.
+
+**How:**
+Implement a stable Studio-side projection rule such as `semanticKey -> editor-semantic-<semanticKey>` and apply those classes to semantic spans without any semantic translation layer.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`
+- any adjacent presentation/style support files
+
+### Step 3 - Load FE-owned resources and remove generic FE ownership path
+
+**What:**
+Load FE-owned stylesheet resources rather than Studio-owned generic FE semantic CSS.
+
+**How:**
+Use descriptor resources surfaced through LSP, attach the referenced stylesheet(s) to the editor presentation/runtime flow, and stop depending on generic `fe.css` as the semantic owner for FE documents.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
+- `prometeu-studio/src/main/resources/themes/editor/presentations/fe.css` if retired or narrowed
+
+### Step 4 - Implement graceful no-highlight degradation
+
+**What:**
+Ensure Studio continues to work without semantic highlight when descriptor/resources are absent.
+
+**How:**
+When the descriptor is absent or resources cannot be consumed, skip semantic styling for that frontend document, preserve editor usability, and avoid user-facing Studio errors.
+
+**File(s):**
+- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
+- semantic highlight routing/presentation files in the editor workspace
+
+### Step 5 - Add Studio tests for FE-owned semantic presentation consumption
+
+**What:**
+Cover descriptor consumption, class projection, and no-highlight degradation.
+
+**How:**
+Add editor-side tests that assert Studio consumes descriptor data, applies projected classes, and keeps operating when descriptor/resources are missing.
+
+**File(s):**
+- `prometeu-studio/src/test/java/p/studio/workspaces/editor/...`
+
+## Test Requirements
+
+### Unit Tests
+- Editor highlight routing tests for semantic key projection.
+- Presentation registry tests for descriptor-driven resource loading.
+- No-highlight degradation tests when descriptor/resources are absent.
+
+### Integration Tests
+- End-to-end Studio/LSP test using a frontend document with FE-owned semantic keys and FE-owned stylesheet resources.
+
+### Manual Verification
+- Open a PBS document and verify semantic colors come from FE-owned presentation resources, not generic Studio FE theme assumptions.
+- Temporarily remove or break the descriptor/resource and verify the editor remains usable with no semantic highlight.
+
+## Acceptance Criteria
+
+- [ ] Studio consumes frontend-owned semantic presentation descriptor data from LSP.
+- [ ] Studio projects semantic keys mechanically to CSS classes.
+- [ ] Generic Studio-owned frontend semantic presentation is no longer the runtime owner for FE highlight.
+- [ ] Missing descriptor/resources degrade to no highlight without Studio UI errors.
+- [ ] Studio tests cover the new descriptor consumption path.
+
+## Dependencies
+
+- Depends on `DEC-0012`.
+- Depends on `PLN-0027` for descriptor and resource publication.
+- Can run after or in parallel with `PLN-0026`, but should not merge before the contract surface in `PLN-0027` exists.
+
+## Risks
+
+- Existing Studio presentation registry may assume static local stylesheets and need a broader refactor.
+- Descriptor-driven resource loading can accidentally leak stylesheet accumulation if lifecycle cleanup is not handled carefully.
+- Partial migration may leave residual `fe.css` assumptions in tests or runtime paths.