115 lines
5.0 KiB
Markdown
115 lines
5.0 KiB
Markdown
---
|
|
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.
|