Frontend Visual Theme Spec and Retirement of Host-Consumed Semantic CSS

2026-05-06 13:43:28 +01:00 · 2026-05-06 13:43:28 +01:00 · baf9f90c93
commit baf9f90c93
parent 0cafe84da0
8 changed files with 766 additions and 35 deletions
--- a/discussion/index.ndjson
+++ b/discussion/index.ndjson
@ -1,4 +1,5 @@
-{"type":"meta","next_id":{"DSC":33,"AGD":36,"DEC":33,"PLN":68,"LSN":47,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":34,"AGD":37,"DEC":34,"PLN":72,"LSN":47,"CLSN":1}}
 {"type":"discussion","id":"DSC-0033","status":"in_progress","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-06","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[{"id":"AGD-0036","file":"AGD-0036-frontend-visual-theme-spec-and-css-retirement.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06"}],"decisions":[{"id":"DEC-0033","file":"DEC-0033-frontend-visual-theme-spec-and-css-retirement.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06","ref_agenda":"AGD-0036"}],"plans":[{"id":"PLN-0068","file":"PLN-0068-frontend-visual-contract-and-pbs-migration.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0069","file":"PLN-0069-lsp-visual-theme-transport-and-selection.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0070","file":"PLN-0070-studio-visual-theme-adapter-and-css-retirement.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]},{"id":"PLN-0071","file":"PLN-0071-vscode-dynamic-theme-translation-adapter.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0033"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0032","status":"in_progress","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-05","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[{"id":"AGD-0035","file":"AGD-0035-studio-new-lsp-api-and-v1-boundary.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05"}],"decisions":[{"id":"DEC-0032","file":"DEC-0032-studio-new-lsp-api-and-v1-boundary.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05","ref_agenda":"AGD-0035"}],"plans":[{"id":"PLN-0065","file":"PLN-0065-lsp-boundary-and-module-scaffolding.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]},{"id":"PLN-0066","file":"PLN-0066-project-scoped-lsp-server-lifecycle-in-studio.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]},{"id":"PLN-0067","file":"PLN-0067-compiler-backed-dumb-lsp-server-baseline.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0031","status":"in_progress","ticket":"studio-editor-workspace-cleanup","title":"Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados","created_at":"2026-05-05","updated_at":"2026-05-05","tags":["studio","editor","cleanup","vfs","lsp","migration"],"agendas":[{"id":"AGD-0034","file":"AGD-0034-vscode-editor-migration-feasibility.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-studio-editor-workspace-cleanup.md","status":"in_progress","created_at":"2026-05-05","updated_at":"2026-05-05","ref_agenda":"AGD-0034"}],"plans":[{"id":"PLN-0062","file":"PLN-0062-shell-session-and-state-cleanup-after-editor-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0063","file":"PLN-0063-legacy-lsp-and-vfs-module-removal-with-runtime-preservation.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0064","file":"PLN-0064-normative-test-and-lesson-cleanup-for-editor-stack-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0030","status":"done","ticket":"studio-scene-pack-runtime-binary-contract","title":"Studio scene pack contract for runtime SCENE binary payload","created_at":"2026-04-24","updated_at":"2026-05-01","tags":["studio","packer","runtime","scene","asset-pack","binary-format","tiled"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0030-studio-scene-pack-runtime-binary-contract/LSN-0046-canonical-scene-owns-editorial-truth-while-pack-stays-request-driven.md","status":"done","created_at":"2026-05-01","updated_at":"2026-05-01"}]}
--- a/discussion/workflow/agendas/AGD-0036-frontend-visual-theme-spec-and-css-retirement.md
+++ b/discussion/workflow/agendas/AGD-0036-frontend-visual-theme-spec-and-css-retirement.md
@ -0,0 +1,147 @@
 ---
 id: AGD-0036
 ticket: frontend-visual-theme-spec-and-css-retirement
 title: Frontend Visual Theme Spec and Retirement of Host-Consumed Semantic CSS
 status: accepted
 created: 2026-05-06
 resolved: 2026-05-06
 decision: DEC-0033
 tags: [compiler, compiler-general, frontend, presentation, theming, studio, vscode, lsp, pbs]
 ---
 ## Pain
 The current semantic highlighting path is no longer strong enough now that Prometeu must project frontend-owned presentation into more than one host.
 Today the frontend still effectively ships a host-facing CSS file as the practical source of truth for visual presentation.
 That works tolerably for the legacy Studio editor path, but it collapses once the same frontend presentation must be exported to VS Code through LSP semantic tokens.
 The result is a weak cross-host contract:
 - the frontend publishes semantic keys, but not a complete visual spec,
 - `semantic-highlighting.css` still acts as the real authored presentation artifact,
 - VS Code only receives a partial hand-translated approximation,
 - and each host risks drifting away from the frontend's intended visual identity.
 The CSS file should be treated as migration input only and must die by the end of this refactor.
 ## Context
 Domain owner: `compiler/general`
 Propagation targets are expected in at least three places:
 - compiler frontend metadata and contracts,
 - Studio host consumption,
 - VS Code extension host consumption.
 Relevant historical context already exists in `LSN-0029`, which established frontend ownership of semantic presentation metadata through `FrontendSpec`.
 That lesson is still useful for ownership boundaries, but it is not sufficient for the next wave because the current contract is too weak and too resource-oriented.
 Current state:
 - `FrontendSemanticPresentationSpec` exposes only `semanticKeys` and opaque `resources`,
 - PBS publishes `/themes/pbs/semantic-highlighting.css` as a semantic presentation resource,
 - Studio can consume that resource directly,
 - VS Code cannot consume that CSS directly and must approximate it via `package.json` and semantic token theming,
 - recent LSP work now transports PBS semantic token types, but the host-side rendering still falls short of the original PBS editor look.
 What is missing is a frontend-owned visual spec that is structured enough to be exported to multiple hosts without making CSS the canonical source.
 ## Open Questions
 - [x] What is the canonical replacement for `semantic-highlighting.css` inside `FrontendSpec`?
  R: a structured visual presentation spec (a JSON) that includes semantic token styles and editor-level colors.
 - [x] Which parts of frontend presentation are normative and cross-host, and which are host-specific adapters only?
  R: a ideia eh que o FE presentation possa ser completamente expostado para os clientes como o VSCode.
 - [x] Should the visual contract be semantic-token-centric only, or should it also include editor-level colors such as base foreground, selection, gutter, and accent surfaces?
  R: o contrato visual pode ofertar toda essa gama de atributos para cada token, o cliente (VSCode) pode usa-los para compor o tema, mas o contrato deve ser token-centric para garantir que a intenção visual seja sempre atrelada a chaves semânticas.
 - [x] How should Studio consume the new visual spec without keeping CSS as a hidden canonical source?
  R: o FE Presentation na medida que o servidor eh described oferece um contrato visual estruturado, o cliente (VSCode extension) deve consumir esse contrato e gerar o que tiver que gerar para compor o tema. Se o cliente usar CSS que gere isso.
 - [x] How should VS Code consume the new visual spec: static generated contribution, runtime translation, or both?
  R: A ideia eh que o cliente seja bem burro, ele deve ser uma maquina que traduz o contrato visual para um formato que o VSCode entenda, seja isso um contribution estatico ou uma tradução dinamica, o importante eh que o contrato visual seja o unico input e a fonte de verdade para a intencao visual do frontend.
 - [x] How do we phase out existing frontend-owned CSS resources without breaking current Studio rendering during migration?
  R: nada no studio depende desse CSS, ele eh um artefato de migração para o PBS. O contrato visual deve ser definido e implementado no PBS primeiro, usando o CSS como input para derivar o formato estruturado. Depois disso, o CSS pode ser descontinuado.
 - [x] How do we version and validate the visual contract so new frontends can implement it consistently?
  R: o contrato deve viver dentro de `FrontendSpec` e ser versionado junto com ele.
 ## Options
 ### Option A - Keep CSS as the canonical frontend artifact and add exporters around it
 - **Approach:** Preserve `semantic-highlighting.css` as the frontend-owned source and build tooling that parses or translates it into Studio and VS Code outputs.
 - **Pro:** Smallest migration cost in the short term, because PBS already has authored CSS.
 - **Con:** Keeps host-facing CSS as the source of truth, which is the wrong abstraction for multi-host consumption and weak for validation.
 - **Maintainability:** Poor. Every new host would need a CSS interpretation path or a CSS-to-host adapter with lossy translation rules.
 ### Option B - Introduce a structured frontend visual spec and treat CSS as a temporary migration input
 - **Approach:** Replace the current resource-centric semantic presentation contract with a structured visual spec published by the frontend. Use the existing CSS only as bootstrap input while migrating PBS, then retire it as canonical data.
 - **Pro:** Creates a real multi-host contract that can be exported mechanically to Studio and VS Code while preserving frontend ownership.
 - **Con:** Requires contract design, adapter work in both hosts, and a migration story for current frontend resources.
 - **Maintainability:** Strong. New frontends would author one canonical visual contract and hosts would implement stable adapters.
 ### Option C - Split the contract into semantic vocabulary plus host-owned themes
 - **Approach:** Keep frontend ownership only over semantic keys and let each host define its own visual theme for those keys.
 - **Pro:** Simplifies frontend metadata and gives each host more freedom.
 - **Con:** Reintroduces host ownership over frontend meaning in practice and guarantees visual drift between Studio and VS Code.
 - **Maintainability:** Medium at best. It reduces frontend burden but loses the core requirement of frontend-owned identity.
 ## Tradeoffs
 Option A looks attractive because it reuses existing assets, but it cements the wrong boundary.
 If CSS remains canonical, the compiler/frontend layer still cannot describe its own presentation in a host-neutral way.
 Option C is cleaner than the current situation from a tooling perspective, but it fails the product goal.
 The user experience would vary per host because visual meaning would no longer be frontend-owned.
 Option B is the only direction that preserves the previous ownership decision while extending it into a credible cross-host architecture.
 Its cost is real, but that cost is exactly the work we need to make the contract durable.
 ## Recommendation
 Adopt Option B.
 The frontend should publish a structured visual presentation spec as canonical data.
 That spec should become the only normative source for frontend semantic/editor appearance that is intended to survive across hosts.
 `semantic-highlighting.css` should be used only as migration input for PBS while we derive the first structured visual spec.
 After migration, CSS may remain as a generated Studio adapter artifact for a while, but it must no longer be treated as authored truth.
 The new contract likely needs at least these conceptual layers:
 - semantic token styles,
 - editor surface colors,
 - optional UI accent colors tied to the editing surface,
 - explicit host adapter boundaries.
 The LSP path should transport structured visual data or enough structured metadata for the VS Code extension to render the same frontend-owned intent without reverse-engineering CSS.
 ## Discussion
 This agenda is intentionally narrower than “general editor theming”.
 The problem is not to invent a universal Prometeu theme engine first.
 The problem is to stop using frontend-authored CSS as the canonical semantic/editor presentation contract and replace it with a frontend-owned visual spec that survives host translation.
 The most important discipline point is ownership:
 - compiler/frontend owns semantic and visual intent,
 - LSP transports frontend-owned intent,
 - Studio and VS Code are rendering adapters,
 - host adapters may have capability gaps, but they must not become canonical.
 There is also an important migration constraint:
 - PBS is the first frontend and will define the initial shape,
 - but the contract must not become “PBS-specific metadata with generic naming later”,
 - instead it must be valid as a compiler-general surface that PBS implements first.
 ## Resolution
 Accepted on 2026-05-06.
 The discussion resolves in favor of a structured frontend-owned visual theme specification with support for multiple themes per frontend.
 Themes remain tied to the frontend's own semantic vocabulary.
 Studio and the VS Code extension act as adapters over that contract.
 `semantic-highlighting.css` remains migration input only and must be retired as canonical authored truth.
--- a/discussion/workflow/decisions/DEC-0033-frontend-visual-theme-spec-and-css-retirement.md
+++ b/discussion/workflow/decisions/DEC-0033-frontend-visual-theme-spec-and-css-retirement.md
@ -0,0 +1,152 @@
 ---
 id: DEC-0033
 ticket: frontend-visual-theme-spec-and-css-retirement
 title: Frontend-owned visual theme spec as canonical presentation contract
 status: accepted
 created: 2026-05-06
 accepted: 2026-05-06
 agenda: AGD-0036
 plans: [PLN-0068, PLN-0069, PLN-0070, PLN-0071]
 tags: [compiler, compiler-general, frontend, presentation, theming, studio, vscode, lsp, pbs]
 ---
 ## Decision
 Prometeu SHALL replace frontend-authored host-consumed semantic CSS with a structured frontend-owned visual theme specification as the canonical presentation contract.
 This decision locks the following normative points:
 1. Each `FrontendSpec` MUST publish its own semantic vocabulary and MAY publish multiple visual themes for that vocabulary.
 2. Visual themes MUST be frontend-owned and MUST remain associated with the semantic tokens defined by that same frontend.
 3. `semantic-highlighting.css` MUST be treated as migration input only and MUST cease to be an authored canonical contract by the end of this refactor.
 4. Studio and the VS Code extension MUST act as rendering adapters over the frontend-owned visual contract and MUST NOT become owners of frontend theme data.
 5. The VS Code extension MUST translate the frontend visual contract dynamically or mechanically from the contract itself, so frontend visual adjustments do not require extension maintenance for each theme change.
 ## Rationale
 The current model is structurally weak for multi-host consumption.
 PBS still carries a CSS resource that works as the practical source of visual truth, while VS Code can only consume a partial manual approximation through semantic token configuration.
 That creates the wrong ownership boundary:
 1. the frontend owns semantic meaning but does not fully own its exported visual contract;
 2. hosts are forced to reinterpret or approximate visual intent;
 3. every frontend visual adjustment risks requiring host edits;
 4. visual drift becomes likely across Studio and VS Code.
 The repository already established that semantic presentation belongs to the frontend.
 This decision extends that ownership model into a stronger cross-host contract:
 1. the frontend authors semantic and visual intent once;
 2. LSP transports that intent;
 3. hosts adapt it without redefining it.
 ## Technical Specification
 ### 1. Canonical Visual Contract
 `FrontendSpec` MUST evolve to expose a structured visual presentation contract as canonical data.
 That contract MUST:
 1. live with the frontend definition;
 2. be versioned together with `FrontendSpec`;
 3. be sufficient for multiple hosts to render the frontend's intended appearance without interpreting CSS as the source of truth;
 4. remain compiler-general even if PBS is the first frontend to implement it.
 The canonical contract MAY be encoded as JSON-backed structured data or as an equivalent strongly-typed model, but the authored source of truth MUST be the structured visual contract, not CSS.
 ### 2. Frontend-Owned Themes
 Each frontend MAY publish multiple visual themes.
 Rules:
 1. themes MUST belong to the frontend that defines the semantic vocabulary they style;
 2. themes MUST be expressed in terms of that frontend's own semantic token keys and related editor presentation surfaces;
 3. hosts MAY select which frontend theme is active;
 4. hosts MUST NOT redefine the theme contract as host-owned authored data.
 This means theme ownership is:
 1. frontend authors themes,
 2. host selects and applies themes,
 3. host does not author the frontend visual semantics.
 ### 3. Token-Centric Contract with Editor Surfaces
 The visual contract MUST be token-centric, but it SHALL also support editor-level presentation data where needed to preserve frontend visual intent.
 Therefore the contract MUST be able to express:
 1. token-scoped presentation such as foreground, emphasis, and related token styling attributes;
 2. editor surface colors such as base foreground, selection, gutter, and other editing-surface colors when they are part of frontend visual intent;
 3. optional frontend-specific accents tied to the editing experience.
 Token-centricity remains mandatory because semantic meaning MUST stay anchored to semantic keys.
 Editor-surface data is allowed because semantic fidelity alone is insufficient to reproduce frontend identity across hosts.
 ### 4. Host Adapter Responsibilities
 Studio and the VS Code extension MUST consume the frontend visual contract as adapters.
 Studio:
 1. MUST consume the structured frontend visual contract;
 2. MAY render through generated CSS or another host mechanism;
 3. MUST NOT treat generated CSS as the canonical frontend artifact.
 VS Code extension:
 1. MUST consume the frontend visual contract through the server description path or an equivalent frontend-owned transport surface;
 2. MUST translate that contract into whatever VS Code requires, whether through runtime translation, generated contributions, or another adapter mechanism;
 3. MUST behave as a mechanical translator of the frontend contract;
 4. MUST NOT require hand-maintained extension theme edits whenever a frontend changes a color, emphasis rule, or theme variant.
 ### 5. LSP Transport Responsibilities
 The LSP path MUST transport enough structured frontend-owned visual information for hosts to render the active frontend theme.
 It MUST preserve:
 1. frontend identity,
 2. semantic token identity,
 3. theme identity where multiple themes exist,
 4. visual attributes needed by the host adapter.
 LSP MUST NOT collapse frontend themes into host-authored generic theme categories.
 ### 6. Migration and CSS Retirement
 `semantic-highlighting.css` is allowed only as migration input for the first structured contract derivation.
 Migration rules:
 1. PBS SHALL be the first frontend migrated;
 2. the existing PBS CSS MAY be parsed or manually transcribed into the first canonical structured visual contract;
 3. once the structured contract becomes authoritative, the CSS MUST no longer be treated as authored truth;
 4. any remaining CSS after migration MAY exist only as generated adapter output or as temporary compatibility residue scheduled for removal;
 5. the refactor is not complete while host-consumed semantic CSS remains the canonical frontend presentation source.
 ### 7. Extension Stability Requirement
 This decision explicitly locks an operational requirement for `tools/vscode-extension`:
 1. frontend visual changes MUST be expressible by changing frontend-owned contract data;
 2. such frontend changes MUST NOT force routine extension source edits;
 3. the extension SHALL be stable as a contract adapter rather than a repository of manually curated frontend theme rules.
 ## Constraints
 1. The canonical source of frontend visual intent MUST move out of authored CSS.
 2. Theme ownership MUST remain with the frontend.
 3. The contract MUST support multiple themes per frontend.
 4. The contract MUST remain compiler-general and MUST NOT hardcode PBS as the universal model.
 5. Hosts MUST remain adapters and MUST NOT become fallback authors of frontend visual identity.
 6. Any derived plan MUST include an explicit migration path for PBS and explicit retirement of `semantic-highlighting.css` as canonical data.
 7. Any derived plan MUST cover compiler contract changes, transport propagation, Studio consumption, and VS Code consumption.
 ## Revision Log
 - 2026-05-06: Initial accepted decision from AGD-0036.
 - 2026-05-06: Decomposed into PLN-0068, PLN-0069, PLN-0070, and PLN-0071.
--- a/discussion/workflow/plans/PLN-0068-frontend-visual-contract-and-pbs-migration.md
+++ b/discussion/workflow/plans/PLN-0068-frontend-visual-contract-and-pbs-migration.md
@ -0,0 +1,118 @@
 ---
 id: PLN-0068
 ticket: frontend-visual-theme-spec-and-css-retirement
 title: Frontend Visual Contract and PBS Migration
 status: open
 created: 2026-05-06
 completed:
 tags: [compiler, compiler-general, frontend, pbs, presentation, theming, contract]
 ---
 ## Objective
 Introduce the canonical structured frontend visual contract in `FrontendSpec`, migrate PBS to that contract, and demote `semantic-highlighting.css` from authored truth to migration-only input.
 ## Background
 `DEC-0033` locks that frontend visual intent must become structured canonical data, support multiple themes per frontend, remain token-centric, and retire authored host-consumed semantic CSS as the canonical source.
 PBS is the first frontend and therefore defines the first concrete migration path, but the contract MUST remain compiler-general rather than PBS-shaped by accident.
 ## Scope
 ### Included
 - Evolve compiler/frontend metadata to publish a structured visual contract.
 - Define the contract shape for semantic-token styling, editor surfaces, and theme identity.
 - Migrate PBS to the new contract.
 - Preserve any temporary migration utility needed to derive the first contract from the existing PBS CSS.
 - Add validation tests that make the new contract normative and stable.
 ### Excluded
 - LSP transport changes.
 - Studio rendering changes.
 - VS Code runtime translation changes.
 ## Non-Goals
 - Designing a generic host-owned theme engine.
 - Supporting every possible frontend visual attribute in wave 1.
 - Keeping authored CSS as a parallel canonical source.
 ## Execution Steps
 ### Step 1 - Define the structured visual contract in compiler-general surfaces
 **What:** Replace the resource-centric semantic presentation shape with a canonical structured visual contract in `FrontendSpec`.
 **How:** Add or evolve frontend metadata models so each frontend can publish:
 1. semantic token vocabulary ownership,
 2. one or more named visual themes,
 3. token-centric visual rules,
 4. editor-surface colors needed to preserve frontend identity.
 The model MUST be compiler-general and MUST NOT encode PBS-specific assumptions into the shared type system.
 **File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/models/**`, affected frontend registry/definition surfaces.
 ### Step 2 - Define the theme and token rule semantics explicitly
 **What:** Make the contract operational rather than descriptive.
 **How:** Specify exact fields, invariants, and null/empty behavior for:
 1. theme identity,
 2. theme selection metadata if needed at the contract layer,
 3. token style rules,
 4. editor surface colors,
 5. versioning semantics inside or alongside `FrontendSpec`.
 The implementation MUST make it possible for hosts to translate the contract mechanically without inferring missing meaning.
 **File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**`, associated tests in compiler modules.
 ### Step 3 - Migrate PBS from authored CSS truth to structured contract truth
 **What:** Make PBS the first frontend to author the new contract.
 **How:** Update `PBSDefinitions` and related PBS presentation metadata to publish one or more frontend-owned themes through the new contract. The existing `semantic-highlighting.css` MAY be parsed or manually transcribed to bootstrap the migration, but once the structured contract is in place, CSS MUST no longer be treated as authored truth.
 **File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**`, `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/themes/pbs/**`, related PBS tests.
 ### Step 4 - Lock contract validity with tests
 **What:** Prevent future drift back to opaque resource ownership.
 **How:** Add tests that assert:
 1. frontends publish structured visual themes,
 2. PBS token vocabulary and theme definitions are coherent,
 3. required token styles and editor-surface data resolve correctly,
 4. authored CSS is no longer the canonical contract source.
 **File(s):** compiler-general and PBS test suites.
 ## Test Requirements
 ### Unit Tests
 - Validate model invariants for theme IDs, token rules, and editor-surface fields.
 - Validate `FrontendSpec` copies and exposes structured theme data safely.
 - Validate PBS publishes at least one coherent theme using the new contract.
 ### Integration Tests
 - Run targeted compiler and PBS tests proving the contract compiles, resolves, and remains discoverable through frontend definitions.
 ### Manual Verification
 - Inspect the PBS frontend definition and confirm the structured contract is the readable authored source of truth.
 - Confirm any remaining CSS is clearly migration-only or generated-output-only.
 ## Acceptance Criteria
 - [ ] `FrontendSpec` publishes a structured canonical visual contract.
 - [ ] The contract supports multiple themes per frontend.
 - [ ] The contract is token-centric and can also express editor-surface colors.
 - [ ] PBS is migrated to the new contract.
 - [ ] `semantic-highlighting.css` is no longer treated as authored canonical frontend presentation data.
 ## Dependencies
 - `DEC-0033` accepted and normatively locked.
 ## Risks
 - Overfitting the first contract to PBS would weaken future frontend adoption.
 - An underspecified token-style model would force host inference and violate the decision.
 - Keeping CSS alive as a silent parallel truth source would nullify the migration.
--- a/discussion/workflow/plans/PLN-0069-lsp-visual-theme-transport-and-selection.md
+++ b/discussion/workflow/plans/PLN-0069-lsp-visual-theme-transport-and-selection.md
@ -0,0 +1,114 @@
 ---
 id: PLN-0069
 ticket: frontend-visual-theme-spec-and-css-retirement
 title: LSP Visual Theme Transport and Theme Selection Propagation
 status: open
 created: 2026-05-06
 completed:
 tags: [studio, lsp, protocol, transport, presentation, theming, compiler]
 ---
 ## Objective
 Extend the LSP boundary and transport surfaces so hosts receive frontend-owned visual theme data, theme identity, and active-theme information without collapsing that contract into host-authored categories.
 ## Background
 `DEC-0033` requires LSP to transport enough structured frontend-owned visual information for hosts to render the active frontend theme, preserve frontend and token identity, and avoid forcing the extension to keep hand-maintained theme rules.
 The compiler contract itself is handled by `PLN-0068`. This plan covers the transport boundary that carries that contract into host adapters.
 ## Scope
 ### Included
 - Extend internal LSP-facing description or capability surfaces to expose structured frontend visual contract data.
 - Transport theme identity and active-theme information where needed.
 - Preserve semantic token identity and frontend ownership through mapping layers.
 - Add transport-level tests for the new visual contract payloads.
 ### Excluded
 - Defining the compiler-general contract itself.
 - Studio-side rendering implementation.
 - VS Code-side rendering implementation.
 ## Non-Goals
 - Inventing host-owned fallback theme categories.
 - Expanding LSP beyond what is required to carry the visual contract.
 - Building transport that requires hand-curated per-frontend extension updates.
 ## Execution Steps
 ### Step 1 - Extend internal LSP descriptions to carry visual contract data
 **What:** Evolve the LSP-side server/bridge description surfaces to expose frontend-owned visual contract data instead of ad hoc token metadata only.
 **How:** Update `lsp-api` and `lsp-v1` internal description models so they can carry:
 1. frontend identity,
 2. semantic token legend identity,
 3. available theme definitions or references,
 4. active theme selection.
 The payload shape MUST remain faithful to the frontend contract and MUST NOT normalize it into host-owned abstractions.
 **File(s):** `prometeu-lsp/prometeu-lsp-api/src/main/java/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`.
 ### Step 2 - Thread the visual contract through bridge and mapper layers
 **What:** Ensure the compiler-backed bridge and protocol mappers preserve visual theme data end to end.
 **How:** Update bridge services, protocol mappers, server description responses, and any capability/bootstrap path that currently exposes token data so they now expose the structured visual contract and active theme metadata.
 **File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `.../messages/**`, `.../mapping/**`.
 ### Step 3 - Define theme selection behavior for host consumption
 **What:** Make active-theme semantics operational.
 **How:** Define and implement the transport rule for which theme a host should apply:
 1. single-theme frontend behavior,
 2. multi-theme frontend behavior,
 3. default theme behavior when no host override is in play,
 4. how active-theme selection is surfaced to adapters.
 The transport MUST make host behavior deterministic without host-owned guessing.
 **File(s):** `prometeu-lsp/prometeu-lsp-api/**`, `prometeu-lsp/prometeu-lsp-v1/**`, tests.
 ### Step 4 - Add transport conformance tests
 **What:** Prevent regression back to token-only or host-shaped payloads.
 **How:** Add tests that verify:
 1. theme payloads are present,
 2. token identities survive transport unchanged,
 3. active-theme information is deterministic,
 4. no mapper collapses frontend-owned visual data into host-authored categories.
 **File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, `prometeu-lsp/prometeu-lsp-api/src/test/java/**` if needed.
 ## Test Requirements
 ### Unit Tests
 - Validate DTO/model invariants for theme payloads and active-theme fields.
 - Validate mapper behavior for full visual contract transport.
 ### Integration Tests
 - Run targeted LSP tests proving a compiler-backed frontend description reaches the host adapter layer with visual theme data intact.
 ### Manual Verification
 - Inspect initialize/description pathways and confirm theme metadata is present and frontend-shaped.
 ## Acceptance Criteria
 - [ ] LSP description/transport surfaces carry structured frontend visual theme data.
 - [ ] Theme identity and active-theme semantics are deterministic.
 - [ ] Semantic token identity remains frontend-owned end to end.
 - [ ] No LSP layer introduces host-owned theme abstractions as canonical transport data.
 ## Dependencies
 - `DEC-0033` accepted and normatively locked.
 - `PLN-0068` for the compiler-side contract shape and PBS migration.
 ## Risks
 - Transporting too little theme data would force host inference and violate the decision.
 - Transporting host-shaped payloads would silently recreate the wrong ownership boundary.
 - Theme selection semantics can become ambiguous unless explicitly defined in this plan.
--- a/discussion/workflow/plans/PLN-0070-studio-visual-theme-adapter-and-css-retirement.md
+++ b/discussion/workflow/plans/PLN-0070-studio-visual-theme-adapter-and-css-retirement.md
@ -0,0 +1,101 @@
 ---
 id: PLN-0070
 ticket: frontend-visual-theme-spec-and-css-retirement
 title: Studio Visual Theme Adapter and CSS Retirement
 status: open
 created: 2026-05-06
 completed:
 tags: [studio, editor, presentation, theming, adapter, css-retirement]
 ---
 ## Objective
 Make Studio consume the structured frontend visual contract as an adapter, remove any remaining dependency on authored frontend semantic CSS as the canonical source, and keep any host rendering mechanism clearly derivative.
 ## Background
 `DEC-0033` locks that Studio is a rendering adapter over frontend-owned visual themes and that generated CSS is acceptable only as an adapter mechanism, not as the canonical frontend artifact.
 This plan applies that rule to the Studio side of the stack.
 ## Scope
 ### Included
 - Update Studio-side presentation registries or rendering services to consume structured frontend visual contract data.
 - Generate or map host rendering artifacts from the structured contract if Studio still needs CSS or equivalent host render descriptors.
 - Remove reliance on authored frontend semantic CSS as a direct semantic presentation contract.
 - Add Studio tests proving the adapter path is derivative and deterministic.
 ### Excluded
 - Compiler-side contract design.
 - LSP transport contract design.
 - VS Code adapter behavior.
 ## Non-Goals
 - Rebuilding the deleted legacy Studio editor stack.
 - Introducing Studio-owned frontend themes.
 - Preserving authored semantic CSS as a parallel truth source.
 ## Execution Steps
 ### Step 1 - Update Studio presentation consumption to use the structured contract
 **What:** Make Studio consume frontend-owned visual theme data instead of resource-only semantic presentation.
 **How:** Update presentation registries, semantic highlighting services, or other editor-related rendering seams so they resolve structured visual theme data from the frontend description path.
 **File(s):** `prometeu-studio/src/main/java/**`, any remaining editor/presentation adapter surfaces still active after cleanup.
 ### Step 2 - Derive host rendering artifacts from the contract
 **What:** Keep Studio rendering mechanical.
 **How:** If Studio still requires CSS or CSS-like structures, generate or map them from the structured frontend visual contract. The host-generated artifact MUST be clearly derivative and MUST NOT be treated as authored frontend truth.
 **File(s):** `prometeu-studio/src/main/java/**`, possible theme/presentation helper modules, generated resource paths if adopted.
 ### Step 3 - Remove direct canonical dependence on frontend semantic CSS
 **What:** Retire the old consumption model.
 **How:** Remove or rewrite any code path that treats frontend semantic CSS resources as the canonical semantic presentation input. Leave only temporary compatibility or generated-output behavior if strictly needed during rollout.
 **File(s):** `prometeu-studio/**`, related frontend resource loading code.
 ### Step 4 - Add Studio adapter conformance tests
 **What:** Lock the adapter boundary.
 **How:** Add tests that verify:
 1. Studio consumes structured frontend visual themes,
 2. token style rendering inputs are contract-derived,
 3. any generated CSS is derivative,
 4. Studio does not silently fall back to host-authored frontend theme logic.
 **File(s):** `prometeu-studio/src/test/java/**` and any relevant integration test modules.
 ## Test Requirements
 ### Unit Tests
 - Validate contract-to-rendering translation logic.
 - Validate theme selection consumption on the Studio side.
 ### Integration Tests
 - Run targeted Studio-side tests proving frontend presentation resolves from structured contract data and not from authored semantic CSS.
 ### Manual Verification
 - Inspect the Studio path and confirm remaining CSS, if any, is generated or compatibility-only.
 ## Acceptance Criteria
 - [ ] Studio consumes structured frontend visual contract data.
 - [ ] Any Studio-side CSS or equivalent rendering descriptor is derivative, not canonical.
 - [ ] Direct canonical dependence on authored frontend semantic CSS is removed.
 - [ ] Studio does not reauthor frontend visual identity locally.
 ## Dependencies
 - `DEC-0033` accepted and normatively locked.
 - `PLN-0068` for the canonical compiler/frontend contract.
 - `PLN-0069` for transport of visual contract data into the host boundary.
 ## Risks
 - Studio may still hide old CSS assumptions in helper layers unless the migration is exhaustive.
 - Generated CSS can accidentally become the new silent truth source if ownership boundaries are not explicit in code and tests.
 - Residual editor cleanup from earlier refactors may obscure the remaining active consumption path.
--- a/discussion/workflow/plans/PLN-0071-vscode-dynamic-theme-translation-adapter.md
+++ b/discussion/workflow/plans/PLN-0071-vscode-dynamic-theme-translation-adapter.md
@ -0,0 +1,100 @@
 ---
 id: PLN-0071
 ticket: frontend-visual-theme-spec-and-css-retirement
 title: VS Code Dynamic Theme Translation Adapter
 status: open
 created: 2026-05-06
 completed:
 tags: [vscode, extension, lsp, presentation, theming, adapter]
 ---
 ## Objective
 Turn the VS Code extension into a stable adapter that translates frontend-owned visual theme contracts into VS Code-compatible rendering behavior without requiring source edits for routine frontend theme changes.
 ## Background
 `DEC-0033` explicitly locks that the extension must not become a repository of manually curated frontend theme rules. The extension must translate the contract it receives rather than being edited whenever a frontend changes colors, emphasis, or theme variants.
 This plan covers the client-side adapter behavior that satisfies that requirement.
 ## Scope
 ### Included
 - Replace hardcoded per-frontend visual theme rules with dynamic or generated translation based on the transported frontend contract.
 - Define the minimum static VS Code contribution surface still required by the platform.
 - Support multi-theme frontend data consumption and active-theme application.
 - Add extension tests or verification coverage around theme translation.
 ### Excluded
 - Compiler-side contract definition.
 - LSP transport definition.
 - Studio rendering behavior.
 ## Non-Goals
 - Building a general-purpose VS Code theme marketplace artifact.
 - Allowing the extension to become a second authored source of frontend theme truth.
 - Solving unrelated reconnect or transport lifecycle issues beyond what this adapter needs.
 ## Execution Steps
 ### Step 1 - Identify the minimal static VS Code contribution surface
 **What:** Separate what the extension must declare statically from what it can translate dynamically.
 **How:** Keep only the minimal `package.json` contribution data required for VS Code to recognize semantic token kinds or activate the extension. Remove hardcoded frontend-specific color rules from static configuration where dynamic translation can take over.
 **File(s):** `tools/vscode-extension/package.json`, related extension bootstrap files.
 ### Step 2 - Implement contract-to-VS Code theme translation
 **What:** Translate frontend-owned visual contract data into VS Code-understandable configuration.
 **How:** Update extension runtime code to receive the transported visual theme contract, map token and editor-surface data into the VS Code APIs/configuration model, and apply the active frontend theme deterministically.
 **File(s):** `tools/vscode-extension/src/**`, mirrored build outputs only if local toolchain constraints require temporary manual sync.
 ### Step 3 - Support multi-theme frontends without extension source edits
 **What:** Make frontend theme growth operationally cheap.
 **How:** Ensure that adding or changing frontend-owned themes does not require new extension source logic unless the VS Code platform itself introduces a new capability boundary. Theme identity, token rules, and active selection must be data-driven.
 **File(s):** `tools/vscode-extension/src/**`, possible supporting protocol model surfaces if consumed directly.
 ### Step 4 - Add adapter verification coverage
 **What:** Protect the no-manual-theme-maintenance rule.
 **How:** Add tests or deterministic verification around:
 1. translation of token rules,
 2. translation of editor-surface colors where supported,
 3. handling of multiple frontend themes,
 4. absence of hardcoded PBS-only theme logic in the adapter path.
 **File(s):** `tools/vscode-extension/src/test/**` if present, or equivalent test harness/verification approach adopted by the extension module.
 ## Test Requirements
 ### Unit Tests
 - Validate translation of structured token rules into VS Code-compatible theme rules.
 - Validate active-theme switching behavior for data-driven frontend themes.
 ### Integration Tests
 - Run extension-targeted validation proving the frontend contract can change without source-level theme edits.
 ### Manual Verification
 - Open PBS content through the extension and confirm the active theme is applied from transported contract data rather than hardcoded `package.json` color tables.
 ## Acceptance Criteria
 - [ ] The extension no longer depends on hardcoded frontend-specific theme rules as the primary rendering source.
 - [ ] Frontend theme changes are driven by contract data rather than extension source edits.
 - [ ] Multi-theme frontend payloads can be translated and applied deterministically.
 - [ ] The remaining static VS Code contribution surface is minimal and structural only.
 ## Dependencies
 - `DEC-0033` accepted and normatively locked.
 - `PLN-0069` for transport of visual theme data to the extension.
 ## Risks
 - VS Code platform constraints may force a hybrid static/runtime model that must stay carefully bounded.
 - The current local Node/TypeScript environment issues can slow validation.
 - Leaving too much theme data in `package.json` would preserve the current maintenance problem under a new name.
--- a/tools/vscode-extension/package.json
+++ b/tools/vscode-extension/package.json
@ -149,40 +149,38 @@
    ],
    "configurationDefaults": {
      "editor.semanticHighlighting.enabled": true,
-      "[pbs]": {
+      "editor.semanticTokenColorCustomizations": {
-        "editor.semanticTokenColorCustomizations": {
+        "enabled": true,
-          "enabled": true,
+        "rules": {
-          "rules": {
+          "pbs-keyword:pbs": "#569cd6",
-            "pbs-keyword": "#569cd6",
+          "pbs-lifecycle:pbs": "#ef50c0",
-            "pbs-lifecycle": "#ef50c0",
+          "pbs-function:pbs": "#f2c14e",
-            "pbs-function": "#f2c14e",
+          "pbs-method:pbs": "#f2c14e",
-            "pbs-method": "#f2c14e",
+          "pbs-constructor:pbs": "#ecdcaa",
-            "pbs-constructor": "#ecdcaa",
+          "pbs-struct:pbs": "#4ec9b0",
-            "pbs-struct": "#4ec9b0",
+          "pbs-contract:pbs": "#78dce8",
-            "pbs-contract": "#78dce8",
+          "pbs-host:pbs": "#b7a2fa",
-            "pbs-host": "#b7a2fa",
+          "pbs-builtin-type:pbs": "#8be9fd",
-            "pbs-builtin-type": "#8be9fd",
+          "pbs-service:pbs": "#b7a2fa",
-            "pbs-service": "#b7a2fa",
+          "pbs-error:pbs": "#ff5b5b",
-            "pbs-error": "#ff5b5b",
+          "pbs-enum:pbs": "#56cfe1",
-            "pbs-enum": "#56cfe1",
+          "pbs-callback:pbs": "#b7a2fa",
-            "pbs-callback": "#b7a2fa",
+          "pbs-global:pbs": {
-            "pbs-global": {
+            "foreground": "#f790fc",
-              "foreground": "#f790fc",
+            "italic": true
-              "italic": true
+          },
-            },
+          "pbs-const:pbs": "#f78c6c",
-            "pbs-const": "#f78c6c",
+          "pbs-implements:pbs": "#a1c181",
-            "pbs-implements": "#a1c181",
+          "pbs-string:pbs": "#00c088",
-            "pbs-string": "#00c088",
+          "pbs-number:pbs": "#ff90b0",
-            "pbs-number": "#ff90b0",
+          "pbs-comment:pbs": {
-            "pbs-comment": {
+            "foreground": "#c090b0",
-              "foreground": "#c090b0",
+            "italic": true
-              "italic": true
+          },
-            },
+          "pbs-literal:pbs": "#4fc1ff",
-            "pbs-literal": "#4fc1ff",
+          "pbs-operator:pbs": "#d4d4d4",
-            "pbs-operator": "#d4d4d4",
+          "pbs-punctuation:pbs": "#d4d4d4",
-            "pbs-punctuation": "#d4d4d4",
+          "pbs-identifier:pbs": "#d4d4d4"
            "pbs-identifier": "#d4d4d4"
          }
        }
      }
    }