---
id: PLN-0027
ticket: studio-frontend-owned-semantic-editor-presentation
title: Add frontend semantic presentation contract to FrontendSpec and expose it through LSP
status: review
created: 2026-04-02
completed:
tags:
  - compiler
  - frontend
  - lsp
  - contract
  - semantic-highlighting
---

## Objective

Implement the frontend-owned semantic presentation contract in `FrontendSpec` and expose a derived descriptor through LSP without collapsing frontend semantics into host-owned categories.

## Background

`DEC-0012` requires:

- static contract data in `FrontendSpec`;
- a simple descriptor containing `semanticKeys + resources`;
- frontend-owned semantic vocabulary using stable `semanticKey` values;
- LSP as a hub that derives and exposes the descriptor to Studio;
- no generic semantic-key reduction such as `fe-keyword`.

## Scope

### Included
- `FrontendSpec` contract model additions.
- FE-specific publication of semantic keys and semantic presentation resources.
- Replacement of generic LSP semantic key emission with frontend-owned keys.
- LSP descriptor derivation and API exposure.
- FE-side tests covering contract presence and consistency.

### Excluded
- Studio CSS application changes.
- Studio presentation registry migration.
- Removal of legacy Studio stylesheets, except where required to avoid compile/runtime conflicts.

## Execution Steps

### Step 1 - Extend FrontendSpec with semantic presentation contract

**What:**
Add a static semantic presentation contract to `FrontendSpec`.

**How:**
Introduce a dedicated descriptor type that carries frontend-owned `semanticKeys + resources`, wire it into `FrontendSpec`, and keep `FrontendSpec` static and frontend-owned.

**File(s):**
- `prometeu-compiler/prometeu-frontend-api/src/main/java/.../FrontendSpec.java`
- any adjacent model files needed for the new descriptor type

### Step 2 - Publish PBS semantic vocabulary and resources through FrontendSpec

**What:**
Make PBS publish frontend-owned semantic keys and highlight resources.

**How:**
Add a frontend-owned semantic vocabulary model such as `PbsSemanticKind -> semanticKey`, publish the resulting semantic presentation contract from PBS frontend definitions, and point the descriptor to FE-owned resources.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java`
- PBS semantic analysis/indexing files that currently assign generic `fe-*` categories
- FE resource directory under the PBS frontend module

### Step 3 - Remove generic semantic key collapse in LSP

**What:**
Stop translating frontend semantics into host-owned generic semantic keys.

**How:**
Replace `fe-keyword`, `fe-type`, and similar outputs with frontend-owned semantic keys coming from frontend semantic vocabulary and/or `FrontendSpec` contract data.

**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
- any LSP DTO/message models that need to surface the descriptor

### Step 4 - Expose descriptor from analysis to Studio-facing LSP results

**What:**
Expose a Studio-consumable descriptor derived from the resolved `FrontendSpec`.

**How:**
Derive the descriptor during analysis/session creation and include it in the LSP surface that Studio consumes for semantic highlight application.

**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/...` messages/DTOs
- any semantic session models involved in transport

### Step 5 - Add FE contract tests

**What:**
Verify the FE contract is present and coherent.

**How:**
Add frontend tests that fail when semantic presentation contract data is missing, when semantic keys are not published, or when published resources do not match the FE contract shape expectations.

**File(s):**
- PBS frontend tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...`
- frontend-api tests if `FrontendSpec` invariants are enforced there

## Test Requirements

### Unit Tests
- `FrontendSpec` tests for semantic presentation descriptor presence and shape.
- PBS frontend tests for semantic key publication.
- LSP tests for transport of frontend-owned semantic keys and descriptor data.

### Integration Tests
- Analyze a PBS file through LSP and assert that returned semantic highlights use PBS-owned semantic keys.
- Assert that the descriptor surfaced to the consumer contains the expected `semanticKeys + resources`.

### Manual Verification
- Inspect LSP payloads/logs to confirm there is no remaining `fe-*` semantic key collapse for PBS.

## Acceptance Criteria

- [ ] `FrontendSpec` exposes a static semantic presentation contract.
- [ ] PBS publishes semantic keys and resources through that contract.
- [ ] LSP no longer emits generic host-owned semantic keys for PBS.
- [ ] LSP exposes a descriptor derived from resolved `FrontendSpec`.
- [ ] FE tests cover missing contract data and contract consistency.

## Dependencies

- Depends on `DEC-0012`.
- Should land before Studio consumption changes in `PLN-0028`.

## Risks

- Existing semantic indexing code is currently host-owned and may require a larger refactor than expected.
- DTO surface changes can ripple through Studio and tests.
- Resource publication conventions may be inconsistent across future frontends if not modeled cleanly now.