From c00fc221bea6e104ea7f3f20463f5f8978cf1193 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 2 Apr 2026 15:03:00 +0100 Subject: [PATCH] FE highlight ownership --- discussion/index.ndjson | 3 +- ...tend-owned-semantic-editor-presentation.md | 223 ++++++++++++++++++ ...tend-owned-semantic-editor-presentation.md | 142 +++++++++++ ...dec-0012-into-studio-and-frontend-specs.md | 113 +++++++++ ...resentation-contract-and-lsp-descriptor.md | 139 +++++++++++ ...d-owned-semantic-presentation-in-studio.md | 132 +++++++++++ 6 files changed, 751 insertions(+), 1 deletion(-) create mode 100644 discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md create mode 100644 discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md create mode 100644 discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md create mode 100644 discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md create mode 100644 discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 2f63c113..7ac22b0e 100644 --- a/discussion/index.ndjson +++ b/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":[]} diff --git a/discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md b/discussion/workflow/agendas/AGD-0015-studio-frontend-owned-semantic-editor-presentation.md new file mode 100644 index 00000000..6b7ab83b --- /dev/null +++ b/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/`. + +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". diff --git a/discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md b/discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md new file mode 100644 index 00000000..602ac7f5 --- /dev/null +++ b/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. diff --git a/discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md b/discussion/workflow/plans/PLN-0026-propagate-dec-0012-into-studio-and-frontend-specs.md new file mode 100644 index 00000000..3f01c6e6 --- /dev/null +++ b/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. diff --git a/discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md b/discussion/workflow/plans/PLN-0027-add-frontend-semantic-presentation-contract-and-lsp-descriptor.md new file mode 100644 index 00000000..9fd066bc --- /dev/null +++ b/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. diff --git a/discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md b/discussion/workflow/plans/PLN-0028-consume-frontend-owned-semantic-presentation-in-studio.md new file mode 100644 index 00000000..7a8fc1cd --- /dev/null +++ b/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-` 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.