Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity

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

Browse Source
This commit is contained in:
bQUARKz 2026-05-06 15:21:15 +01:00
parent 69f5c4abdd
commit cab0e92e60
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
10 changed files with 623 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
discussion/index.ndjson
View File

@ -1,4 +1,5 @@
{"type":"meta","next_id":{"DSC":34,"AGD":37,"DEC":34,"PLN":72,"LSN":47,"CLSN":1}}
{"type":"meta","next_id":{"DSC":35,"AGD":38,"DEC":35,"PLN":75,"LSN":47,"CLSN":1}}
{"type":"discussion","id":"DSC-0034","status":"in_progress","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-06","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[{"id":"AGD-0037","file":"AGD-0037-frontend-semantic-host-projection-flexibility.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06"}],"decisions":[{"id":"DEC-0034","file":"DEC-0034-frontend-semantic-host-projection-flexibility.md","status":"accepted","created_at":"2026-05-06","updated_at":"2026-05-06","ref_agenda":"AGD-0037"}],"plans":[{"id":"PLN-0072","file":"PLN-0072-frontend-semantic-host-projection-contract.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0034"]},{"id":"PLN-0073","file":"PLN-0073-lsp-semantic-host-projection-transport.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0034"]},{"id":"PLN-0074","file":"PLN-0074-vscode-semantic-host-projection-adapter.md","status":"open","created_at":"2026-05-06","updated_at":"2026-05-06","ref_decisions":["DEC-0034"]}],"lessons":[]}
{"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":[]}

85
discussion/workflow/agendas/AGD-0037-frontend-semantic-host-projection-flexibility.md Normal file
View File

@ -0,0 +1,85 @@
---
id: AGD-0037
ticket: frontend-semantic-host-projection-flexibility
title: Frontend Semantic Vocabulary Flexibility and Host Projection
status: accepted
created: 2026-05-06
resolved: 2026-05-06
decision: DEC-0034
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
---
## Pain
The current discussion exposed an architectural tension:
- frontend semantic keys must remain frontend-owned and flexible,
- but VS Code prefers host-shaped semantic token categories and modifiers,
- and forcing frontend vocabularies into a rigid global taxonomy would collapse frontend ownership into host constraints.
If Prometeu treats VS Code semantic categories as the canonical semantic contract, the frontend loses semantic freedom and the wrong layer starts owning language meaning.
## Context
Domain owner: `compiler/general`
This discussion extends `DEC-0033` rather than replacing it.
`DEC-0033` already locked that visual themes are frontend-owned and hosts are adapters.
What remained implicit was how a frontend-owned semantic vocabulary should adapt to host capabilities when the host prefers a different semantic model.
The key clarification is:
- the frontend semantic vocabulary remains canonical,
- host adaptation is declarative projection,
- host projection does not become the canonical semantic contract.
## Open Questions
- [x] Should Prometeu define a rigid global semantic token taxonomy shared by every frontend?
R: no. Each frontend keeps its own vocabulary.
- [x] How should VS Code consume flexible frontend vocabularies without becoming the owner of semantic meaning?
R: through a frontend-authored host projection for VS Code.
- [x] Does this revise `DEC-0033`?
R: it complements `DEC-0033` by clarifying semantic vocabulary and host projection responsibilities.
## Options
### Option A - Canonicalize around VS Code token types
- **Approach:** Force frontends to express semantic meaning in a shared VS Code-shaped taxonomy.
- **Pro:** Simplifies host adaptation.
- **Con:** Makes the host model canonical and removes frontend semantic freedom.
- **Maintainability:** Poor. It solves adapter simplicity by weakening frontend ownership.
### Option B - Keep frontend vocabularies canonical and add declarative host projection
- **Approach:** Let each frontend define its own semantic keys and publish host projection metadata that explains how a host such as VS Code should adapt those keys.
- **Pro:** Preserves frontend semantic ownership while keeping host adaptation mechanical.
- **Con:** Requires an additional contract layer.
- **Maintainability:** Strong. Ownership stays correct and adapters remain declarative.
## Tradeoffs
Option A would make the current VS Code situation easier, but only by moving semantic authorship to the wrong layer.
Option B adds contract surface, but that surface is the correct one because it keeps the frontend canonical and makes host projection explicit rather than implicit.
## Recommendation
Adopt Option B.
Frontend semantic keys remain canonical and flexible.
Hosts such as VS Code consume a declarative projection authored by the frontend for that host.
## Discussion
This discussion is intentionally narrow.
It does not reopen the frontend-owned visual theme decision.
It only clarifies that semantic vocabulary itself must also remain frontend-owned, and that host adaptation must be expressed as projection rather than normalization into a rigid shared taxonomy.
## Resolution
Accepted on 2026-05-06.
Prometeu keeps frontend-owned semantic vocabularies flexible and introduces declarative host projection as the adaptation mechanism for hosts such as VS Code.

112
discussion/workflow/decisions/DEC-0034-frontend-semantic-host-projection-flexibility.md Normal file
View File

@ -0,0 +1,112 @@
---
id: DEC-0034
ticket: frontend-semantic-host-projection-flexibility
title: Frontend semantic vocabularies remain canonical and hosts consume declarative projections
status: accepted
created: 2026-05-06
accepted: 2026-05-06
agenda: AGD-0037
plans: [PLN-0072, PLN-0073, PLN-0074]
tags: [compiler, compiler-general, frontend, semantics, vscode, host-projection, lsp]
---
## Decision
Prometeu SHALL keep semantic vocabularies frontend-owned and canonical.
Hosts such as VS Code SHALL consume declarative host projection data authored by the frontend instead of forcing frontend semantic keys into a rigid shared host taxonomy.
This decision locks the following normative points:
1. Each frontend MUST remain free to define its own semantic keys.
2. Prometeu MUST NOT introduce a rigid global semantic token taxonomy as the canonical contract for all frontends.
3. Host-facing semantic adaptation MUST happen through frontend-authored host projection metadata.
4. Host projection metadata MUST be declarative and MUST NOT become the canonical semantic vocabulary.
5. VS Code adaptation MUST consume the frontend semantic vocabulary plus its VS Code projection, not reinterpret semantic meaning ad hoc inside the extension.
## Rationale
The current stack already establishes frontend ownership over visual themes.
Without this complementary rule, semantic vocabulary itself could still drift toward host ownership because VS Code prefers a different semantic model than a frontend may naturally publish.
If the repository made VS Code token categories canonical, it would:
1. collapse frontend semantic freedom,
2. move semantic authorship into the host layer,
3. and make frontend evolution hostage to one specific adapter model.
Declarative host projection preserves the correct ownership boundary:
1. frontend defines semantic meaning,
2. frontend also defines how a given host should project that meaning,
3. host adapters translate mechanically.
## Technical Specification
### 1. Canonical Semantic Vocabulary
The canonical semantic vocabulary for a document language MUST live in that frontend's contract surface.
This implies:
1. semantic keys remain frontend-owned,
2. semantic keys MAY vary significantly between frontends,
3. semantic keys MUST NOT be rewritten into a mandatory repository-wide host-shaped taxonomy.
### 2. Host Projection Contract
Frontend metadata MUST evolve to support host projection descriptors.
At minimum, a host projection descriptor for VS Code MUST be capable of expressing:
1. which canonical semantic key is being projected,
2. which VS Code semantic token type should receive that key,
3. which VS Code semantic token modifiers, if any, should accompany that projection,
4. any fallback behavior needed when the host cannot represent the frontend key exactly.
The host projection descriptor MAY support other hosts later, but the first required host projection is VS Code.
### 3. Ownership Rules
Ownership SHALL be:
1. frontend owns semantic keys,
2. frontend owns host projection metadata,
3. LSP transports both,
4. the host adapter translates both.
The extension MUST NOT become the place where semantic meaning is hand-mapped or reauthored as code-driven policy.
### 4. Relationship to DEC-0033
This decision complements `DEC-0033`.
`DEC-0033` remains normative for:
1. frontend-owned visual theme contracts,
2. frontend-owned theme variants,
3. host adapter responsibilities for visual rendering.
This decision adds the semantic vocabulary clarification that `DEC-0033` left implicit:
1. semantic vocabularies remain frontend-owned and flexible,
2. host adaptation is projection, not normalization.
### 5. VS Code Adapter Rule
For VS Code specifically:
1. the extension MUST consume frontend-owned semantic keys,
2. the extension MUST consume frontend-authored VS Code projection metadata,
3. the extension MUST apply that projection mechanically,
4. the extension MUST NOT force every frontend into a single rigid shared semantic taxonomy to satisfy VS Code.
## Constraints
1. No plan derived from this decision may replace frontend semantic keys with a mandatory global host taxonomy.
2. Any plan touching VS Code semantic adaptation MUST include declarative host projection support.
3. Any plan touching LSP transport for semantic vocabularies MUST preserve frontend canonical keys.
4. This decision MUST be treated as complementary to `DEC-0033`, not as a rollback of frontend-owned theming.
## Revision Log
- 2026-05-06: Initial accepted decision from AGD-0037.

119
discussion/workflow/plans/PLN-0072-frontend-semantic-host-projection-contract.md Normal file
View File

@ -0,0 +1,119 @@
---
id: PLN-0072
ticket: frontend-semantic-host-projection-flexibility
title: Frontend Semantic Host Projection Contract
status: open
created: 2026-05-06
completed:
tags: [compiler, compiler-general, frontend, semantics, host-projection, vscode, pbs]
---
## Objective
Introduce the canonical frontend-authored semantic host projection contract in compiler-general frontend metadata and migrate PBS to publish its first VS Code projection without weakening frontend-owned semantic vocabulary.
## Background
`DEC-0034` locks that semantic vocabularies remain frontend-owned and canonical, while hosts such as VS Code consume declarative projection metadata authored by the frontend. The current semantic presentation work already establishes frontend-owned themes through `DEC-0033`, but semantic adaptation still lacks a structured host projection contract.
PBS is the first concrete frontend and therefore the first migration target, but the contract MUST remain compiler-general rather than PBS-shaped.
## Scope
### Included
- Evolve compiler/frontend metadata to publish declarative semantic host projection descriptors.
- Define the contract shape for VS Code semantic token projection.
- Migrate PBS to author VS Code projection metadata for its canonical semantic keys.
- Add tests that lock the contract and prevent host-owned remapping logic from becoming the source of truth.
### Excluded
- LSP transport changes.
- VS Code extension runtime consumption changes.
- Redesigning PBS canonical semantic keys to mimic VS Code categories.
## Non-Goals
- Introducing a global rigid semantic taxonomy across frontends.
- Making VS Code semantic token types the canonical frontend semantic contract.
- Solving projection for every future host in the first wave.
## Execution Steps
### Step 1 - Define compiler-general host projection metadata
**What:** Extend the frontend semantic metadata surfaces to carry host projection descriptors alongside canonical semantic keys.
**How:** Add or evolve compiler-general model types so a frontend can declare, for each host projection entry:
1. the canonical frontend semantic key being projected,
2. the target host identity,
3. the host token type or equivalent target category,
4. any host modifiers,
5. fallback projection semantics when the host cannot represent the key exactly.
The contract MUST preserve the frontend semantic key as canonical and MUST treat projection as derivative metadata.
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/models/**`, related frontend definition surfaces.
### Step 2 - Make projection rules operational and mechanically consumable
**What:** Turn the projection contract into an exact operational surface rather than an informal note.
**How:** Define invariants, null/empty behavior, and lookup rules for projection descriptors, including:
1. host identifier semantics,
2. duplicate or conflicting projection handling,
3. missing projection behavior,
4. fallback behavior representation,
5. safe access patterns from `FrontendSpec`.
The result MUST allow host adapters to translate frontend-authored projection data mechanically without semantic reinterpretation.
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**`, associated compiler-general tests.
### Step 3 - Migrate PBS to author its first VS Code projection
**What:** Make PBS publish its VS Code semantic projection through the new contract.
**How:** Update PBS frontend metadata so its canonical semantic keys remain unchanged while the frontend also declares how each key projects into VS Code semantic token types and modifiers. The authored projection MUST live in PBS frontend metadata and MUST NOT be reauthored inside the extension.
**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**`, related PBS semantic presentation tests.
### Step 4 - Lock the contract with tests
**What:** Prevent future drift toward host-owned semantic policy.
**How:** Add tests that assert:
1. frontends publish projection descriptors through compiler-general metadata,
2. PBS canonical keys remain frontend-owned,
3. PBS VS Code projection resolves mechanically from frontend metadata,
4. no global repository-wide rigid semantic taxonomy is introduced as the canonical contract.
**File(s):** compiler-general and PBS test suites.
## Test Requirements
### Unit Tests
- Validate projection model invariants, including required frontend key linkage and host target fields.
- Validate `FrontendSpec` safely exposes host projection metadata.
- Validate missing and duplicate projection handling.
### Integration Tests
- Run targeted compiler and PBS tests proving host projection metadata compiles, resolves, and remains discoverable through frontend definitions.
### Manual Verification
- Inspect PBS frontend metadata and confirm the VS Code projection is authored there rather than in host adapter code.
- Confirm canonical PBS semantic keys remain readable and unchanged in ownership terms.
## Acceptance Criteria
- [ ] Compiler-general frontend metadata publishes declarative host projection descriptors.
- [ ] The contract preserves canonical frontend semantic keys as the source of truth.
- [ ] The contract supports a VS Code projection without forcing a global rigid taxonomy.
- [ ] PBS authors its VS Code semantic projection through the new contract.
- [ ] Tests lock the contract against host-owned semantic remapping drift.
## Dependencies
- `DEC-0034` accepted and normatively locked.
- `DEC-0033` accepted where semantic presentation metadata already exists and may need coordinated evolution.
## Risks
- Overfitting projection fields to PBS or to VS Code would weaken future frontend flexibility.
- Allowing ambiguous projection semantics would push semantic authorship back into adapters.
- Collapsing canonical keys into host-shaped aliases would violate `DEC-0034`.

107
discussion/workflow/plans/PLN-0073-lsp-semantic-host-projection-transport.md Normal file
View File

@ -0,0 +1,107 @@
---
id: PLN-0073
ticket: frontend-semantic-host-projection-flexibility
title: LSP Semantic Host Projection Transport
status: open
created: 2026-05-06
completed:
tags: [lsp, compiler, frontend, semantics, host-projection, vscode, protocol]
---
## Objective
Transport canonical frontend semantic vocabulary and frontend-authored VS Code host projection metadata through the Prometeu LSP boundary without normalizing semantic meaning inside the transport layer.
## Background
`DEC-0034` requires LSP to carry both canonical frontend semantic keys and frontend-authored host projection metadata, while preserving the ownership boundary between frontend semantics and host adaptation. `DEC-0033` already introduced frontend-authored visual themes through the LSP handshake; semantic host projection must now follow the same ownership model.
## Scope
### Included
- Extend LSP-facing baseline message models to carry semantic host projection metadata.
- Update the compiler-backed language service bridge to resolve and expose that metadata from frontend definitions.
- Update the LSP protocol mapper to publish the transported metadata to the VS Code extension.
- Add tests that prove canonical keys and projection metadata are both preserved across transport.
### Excluded
- Defining the compiler-general projection contract itself.
- Applying the projection inside the VS Code extension.
- Redesigning semantic token classification logic beyond what is needed to expose projection metadata.
## Non-Goals
- Performing semantic normalization inside the LSP layer.
- Collapsing frontend semantic keys into host token types in baseline message models.
- Introducing host-specific semantic rules into `lsp-api` that belong to frontend metadata.
## Execution Steps
### Step 1 - Extend baseline transport models for semantic projection
**What:** Add baseline message shapes that can carry semantic host projection metadata.
**How:** Evolve LSP-facing DTOs so the server description or related handshake payload can transport:
1. frontend language identity,
2. canonical frontend semantic keys,
3. one or more host projection entries for VS Code,
4. any fallback metadata required by the projection contract.
The transport model MUST preserve canonical frontend keys explicitly rather than flattening everything into host token types.
**File(s):** `prometeu-lsp/prometeu-lsp-api/src/main/java/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`.
### Step 2 - Resolve transport payload from compiler frontend metadata
**What:** Make the language service bridge expose semantic host projection metadata from the frontend contract.
**How:** Update compiler-backed bridge code to read canonical semantic keys plus VS Code projection descriptors from the frontend definition and map them into the baseline transport payload without reinterpreting semantic meaning.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`.
### Step 3 - Publish the projection payload through the handshake
**What:** Make the VS Code client able to receive semantic projection metadata at initialization time.
**How:** Update the protocol mapping layer so the initialize result transports canonical semantic keys and VS Code projection metadata through the agreed experimental surface or another current handshake surface, while keeping semantic theming transport from `DEC-0033` intact and coherent.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/**`, related server description surfaces.
### Step 4 - Lock transport behavior with tests
**What:** Prevent future drift toward semantic normalization inside LSP.
**How:** Add tests that assert:
1. canonical frontend semantic keys survive transport,
2. VS Code projection entries survive transport,
3. payload structure remains mechanically consumable by the extension,
4. the transport layer does not replace frontend keys with host token categories.
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, `prometeu-lsp/prometeu-lsp-api` tests if present.
## Test Requirements
### Unit Tests
- Validate mapping from frontend projection metadata into baseline transport DTOs.
- Validate transport serialization of canonical keys plus projection entries.
### Integration Tests
- Run targeted `lsp-v1` tests proving the server handshake exposes both semantic themes and semantic host projection coherently.
### Manual Verification
- Inspect the initialize payload and confirm that frontend semantic keys and VS Code projection metadata are both visible.
- Confirm no layer in LSP rewrites canonical semantic keys into a mandatory host taxonomy.
## Acceptance Criteria
- [ ] LSP transport models carry canonical frontend semantic keys and VS Code projection metadata together.
- [ ] The compiler-backed bridge resolves that metadata directly from frontend definitions.
- [ ] The initialize payload exposes the metadata mechanically to the extension.
- [ ] Tests lock the transport layer against semantic normalization drift.
## Dependencies
- `DEC-0034` accepted and normatively locked.
- `PLN-0072` completes the compiler/frontend projection contract.
- `DEC-0033` transport conventions remain in force for visual theme payloads.
## Risks
- Reusing visual theme payload structures carelessly could blur the boundary between visual and semantic contracts.
- Flattening transport too aggressively could erase canonical frontend key identity.
- Excessive protocol specialization could make future hosts harder to add.

109
discussion/workflow/plans/PLN-0074-vscode-semantic-host-projection-adapter.md Normal file
View File

@ -0,0 +1,109 @@
---
id: PLN-0074
ticket: frontend-semantic-host-projection-flexibility
title: VS Code Semantic Host Projection Adapter
status: open
created: 2026-05-06
completed:
tags: [vscode, extension, frontend, semantics, host-projection, adapter]
---
## Objective
Make the VS Code extension consume frontend-authored semantic host projection metadata mechanically so semantic highlighting behavior no longer depends on extension-owned assumptions about frontend semantic key names.
## Background
`DEC-0034` makes the frontend semantic vocabulary canonical and requires VS Code adaptation to follow frontend-authored projection metadata rather than an extension-owned taxonomy. `DEC-0033` already moved visual theme ownership into frontend-authored runtime payloads; the semantic adapter must now follow the same model.
The current extension still contains assumptions about semantic token naming and package-level declarations that do not fully reflect frontend-authored projection data.
## Scope
### Included
- Consume semantic host projection payload from the LSP handshake.
- Translate frontend-authored VS Code projection descriptors into the extension's semantic token registration and runtime theme application flow.
- Reduce extension-owned semantic assumptions to the minimum static structure the VS Code platform requires.
- Add tests or verification hooks that prove the adapter follows frontend-authored projection data mechanically.
### Excluded
- Inventing or redefining canonical semantic meaning inside the extension.
- Reworking compiler semantic classification beyond consuming the delivered keys and projections.
- Solving projection for non-VS Code hosts.
## Non-Goals
- Making the extension the owner of semantic taxonomy policy.
- Hardcoding PBS-specific semantic mapping logic as the authoritative source.
- Guaranteeing a perfect one-to-one rendering match with Studio for every frontend key.
## Execution Steps
### Step 1 - Update extension-side semantic projection models
**What:** Add extension-side runtime shapes for the transported semantic projection payload.
**How:** Extend the VS Code extension client code so it can read and store:
1. canonical frontend semantic keys,
2. VS Code projection entries per key,
3. fallback metadata if present,
4. any language-scoped identity needed to apply the projection safely.
These runtime shapes MUST reflect transported frontend-authored metadata rather than a hand-maintained extension mapping table.
**File(s):** `tools/vscode-extension/src/**`, generated `out/**` mirror as needed.
### Step 2 - Apply projection mechanically in the semantic adapter path
**What:** Make the extension derive VS Code-facing semantic behavior from the transported projection.
**How:** Update extension logic so semantic token registration, selectors, and any runtime semantic color rule generation consume the frontend-authored projection entries. The adapter MUST treat missing projection data as a fallback condition, not as permission to reauthor semantic meaning broadly in extension code.
**File(s):** `tools/vscode-extension/src/extension.ts`, related extension helper modules if introduced, generated `out/**` mirror as needed.
### Step 3 - Minimize static package-level semantic assumptions
**What:** Reduce static `package.json` semantic declarations to the minimum platform-required scaffolding.
**How:** Audit the extension manifest and runtime so static declarations remain only where VS Code requires them structurally. Any semantic mapping policy that can be expressed by frontend-authored projection data MUST move out of the manifest and into runtime translation logic.
**File(s):** `tools/vscode-extension/package.json`, `tools/vscode-extension/src/**`.
### Step 4 - Lock adapter behavior with tests and verification
**What:** Prevent regression toward extension-owned semantic policy.
**How:** Add tests or targeted verification code that assert:
1. the adapter reads frontend-authored projection payloads,
2. semantic rules derive from projection data rather than hardcoded PBS assumptions,
3. fallback paths stay bounded and explicit,
4. frontend projection updates do not require extension semantic remapping edits for ordinary token adjustments.
**File(s):** extension test surfaces if present, otherwise targeted runtime assertions and documented manual verification paths.
## Test Requirements
### Unit Tests
- Validate parsing of semantic projection payloads from the initialize response.
- Validate transformation from projection entries into VS Code semantic token rule inputs.
### Integration Tests
- If extension test infrastructure exists, verify that a mock initialize payload drives semantic adapter behavior without code-level remapping tables.
### Manual Verification
- Reload the extension and inspect runtime behavior with a PBS project to confirm semantic highlighting is driven by transported projection data.
- Confirm that a frontend-authored projection change would only require frontend/LSP updates, not new semantic mapping logic in the extension.
## Acceptance Criteria
- [ ] The extension consumes canonical semantic keys and VS Code projection metadata from the LSP handshake.
- [ ] Semantic adapter behavior derives mechanically from transported projection data.
- [ ] Static extension manifest assumptions are reduced to platform-required scaffolding.
- [ ] The extension no longer acts as the authoritative source of frontend semantic mapping policy.
## Dependencies
- `DEC-0034` accepted and normatively locked.
- `PLN-0073` completes LSP transport of semantic host projection metadata.
- `DEC-0033` dynamic visual theme translation remains in place and coherent with semantic adaptation.
## Risks
- VS Code manifest constraints may still require some static declarations, and those boundaries must stay explicit.
- Weak fallback rules could accidentally recreate extension-owned semantic policy.
- Failure to update generated extension output alongside source would leave the runtime out of sync in the current local environment.

41
prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java
View File

@ -1,10 +1,7 @@
package p.studio.compiler;
import p.studio.compiler.models.FrontendSpec;
import p.studio.compiler.models.FrontendEditorPaletteSpec;
import p.studio.compiler.models.FrontendSemanticPresentationSpec;
import p.studio.compiler.models.FrontendTokenStyleSpec;
import p.studio.compiler.models.FrontendVisualThemeSpec;
import p.studio.compiler.models.FrontendSpec;
import p.studio.compiler.pbs.PbsSemanticKind;
import p.studio.utilities.structures.ReadOnlySet;
@ -19,41 +16,7 @@ public class PBSDefinitions {
.stdlibVersions(List.of(FrontendSpec.Stdlib.asDefault(1)))
.semanticPresentation(new FrontendSemanticPresentationSpec(
PbsSemanticKind.semanticKeys(),
List.of(new FrontendVisualThemeSpec(
"pbs-default",
"PBS Default",
new FrontendEditorPaletteSpec(
"#d9e2ec",
"#2d4f6b",
"#2d4f6b",
"#6f8193",
"#2c2140",
"#a47dff",
"#efe6ff"),
List.of(
new FrontendTokenStyleSpec("pbs-comment", "#c090b0", true, false, false),
new FrontendTokenStyleSpec("pbs-string", "#00c088", false, false, false),
new FrontendTokenStyleSpec("pbs-number", "#ff90b0", false, false, false),
new FrontendTokenStyleSpec("pbs-literal", "#4fc1ff", false, false, false),
new FrontendTokenStyleSpec("pbs-lifecycle", "#ef50c0", false, false, false),
new FrontendTokenStyleSpec("pbs-keyword", "#569cd6", false, false, false),
new FrontendTokenStyleSpec("pbs-operator", "#d4d4d4", false, false, false),
new FrontendTokenStyleSpec("pbs-punctuation", "#d4d4d4", false, false, false),
new FrontendTokenStyleSpec("pbs-function", "#f2c14e", false, false, false),
new FrontendTokenStyleSpec("pbs-method", "#f2c14e", false, false, false),
new FrontendTokenStyleSpec("pbs-constructor", "#ecdcaa", false, false, false),
new FrontendTokenStyleSpec("pbs-struct", "#4ec9b0", false, false, false),
new FrontendTokenStyleSpec("pbs-contract", "#78dce8", false, false, false),
new FrontendTokenStyleSpec("pbs-host", "#b7a2fa", false, false, false),
new FrontendTokenStyleSpec("pbs-builtin-type", "#8be9fd", false, false, false),
new FrontendTokenStyleSpec("pbs-service", "#b7a2fa", false, false, false),
new FrontendTokenStyleSpec("pbs-error", "#ff5b5b", false, false, false),
new FrontendTokenStyleSpec("pbs-enum", "#56cfe1", false, false, false),
new FrontendTokenStyleSpec("pbs-callback", "#b7a2fa", false, false, false),
new FrontendTokenStyleSpec("pbs-global", "#f790fc", true, false, false),
new FrontendTokenStyleSpec("pbs-const", "#f78c6c", false, false, false),
new FrontendTokenStyleSpec("pbs-implements", "#a1c181", false, false, false),
new FrontendTokenStyleSpec("pbs-identifier", "#d4d4d4", false, false, false)))),
List.of(PBSFrontendThemes.DEFAULT_PBS),
"pbs-default"))
.build();
}

45
prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSFrontendThemes.java Normal file
View File

@ -0,0 +1,45 @@
package p.studio.compiler;
import p.studio.compiler.models.FrontendEditorPaletteSpec;
import p.studio.compiler.models.FrontendTokenStyleSpec;
import p.studio.compiler.models.FrontendVisualThemeSpec;
import java.util.List;
public class PBSFrontendThemes {
public static final FrontendVisualThemeSpec DEFAULT_PBS = new FrontendVisualThemeSpec(
"pbs-default",
"PBS Default",
new FrontendEditorPaletteSpec(
"#d9e2ec",
"#2d4f6b",
"#2d4f6b",
"#6f8193",
"#2c2140",
"#a47dff",
"#efe6ff"),
List.of(
new FrontendTokenStyleSpec("pbs-comment", "#c090b0", true, false, false),
new FrontendTokenStyleSpec("pbs-string", "#00c088", false, false, false),
new FrontendTokenStyleSpec("pbs-number", "#ff90b0", false, false, false),
new FrontendTokenStyleSpec("pbs-literal", "#4fc1ff", false, false, false),
new FrontendTokenStyleSpec("pbs-lifecycle", "#ef50c0", false, false, false),
new FrontendTokenStyleSpec("pbs-keyword", "#569cd6", false, false, false),
new FrontendTokenStyleSpec("pbs-operator", "#d4d4d4", false, false, false),
new FrontendTokenStyleSpec("pbs-punctuation", "#d4d4d4", false, false, false),
new FrontendTokenStyleSpec("pbs-function", "#f2c14e", false, false, false),
new FrontendTokenStyleSpec("pbs-method", "#f2c14e", false, false, false),
new FrontendTokenStyleSpec("pbs-constructor", "#ecdcaa", false, false, false),
new FrontendTokenStyleSpec("pbs-struct", "#4ec9b0", false, false, false),
new FrontendTokenStyleSpec("pbs-contract", "#78dce8", false, false, false),
new FrontendTokenStyleSpec("pbs-host", "#b7a2fa", false, false, false),
new FrontendTokenStyleSpec("pbs-builtin-type", "#8be9fd", false, false, false),
new FrontendTokenStyleSpec("pbs-service", "#b7a2fa", false, false, false),
new FrontendTokenStyleSpec("pbs-error", "#ff5b5b", false, false, false),
new FrontendTokenStyleSpec("pbs-enum", "#56cfe1", false, false, false),
new FrontendTokenStyleSpec("pbs-callback", "#b7a2fa", false, false, false),
new FrontendTokenStyleSpec("pbs-global", "#f790fc", true, false, false),
new FrontendTokenStyleSpec("pbs-const", "#f78c6c", false, false, false),
new FrontendTokenStyleSpec("pbs-implements", "#a1c181", false, false, false),
new FrontendTokenStyleSpec("pbs-identifier", "#d4d4d4", false, false, false)));
}

41
test-projects/main/.vscode/settings.json vendored Normal file
View File

@ -0,0 +1,41 @@
{
"editor.semanticTokenColorCustomizations": {
"enabled": true,
"rules": {
"pbs-comment:pbs": {
"foreground": "#c090b0",
"italic": true
},
"pbs-string:pbs": "#00c088",
"pbs-number:pbs": "#ff90b0",
"pbs-literal:pbs": "#4fc1ff",
"pbs-lifecycle:pbs": "#ef50c0",
"pbs-keyword:pbs": "#569cd6",
"pbs-operator:pbs": "#d4d4d4",
"pbs-punctuation:pbs": "#d4d4d4",
"pbs-function:pbs": "#f2c14e",
"pbs-method:pbs": "#f2c14e",
"pbs-constructor:pbs": "#ecdcaa",
"pbs-struct:pbs": "#4ec9b0",
"pbs-contract:pbs": "#78dce8",
"pbs-host:pbs": "#b7a2fa",
"pbs-builtin-type:pbs": "#8be9fd",
"pbs-service:pbs": "#b7a2fa",
"pbs-error:pbs": "#ff5b5b",
"pbs-enum:pbs": "#56cfe1",
"pbs-callback:pbs": "#b7a2fa",
"pbs-global:pbs": {
"foreground": "#f790fc",
"italic": true
},
"pbs-const:pbs": "#f78c6c",
"pbs-implements:pbs": "#a1c181",
"pbs-identifier:pbs": "#d4d4d4"
}
},
"workbench.colorCustomizations": {
"editor.foreground": "#d9e2ec",
"editor.selectionBackground": "#2d4f6b",
"editorLineNumber.foreground": "#6f8193"
}
}