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

This commit is contained in:
2026-05-06 13:43:28 +01:00
parent 0cafe84da0
commit baf9f90c93
8 changed files with 766 additions and 35 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -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.