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

This commit is contained in:
2026-05-06 15:21:15 +01:00
parent 69f5c4abdd
commit cab0e92e60
10 changed files with 623 additions and 41 deletions
@@ -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`.
@@ -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.
@@ -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.