---
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.