---
id: LSN-0029
ticket: studio-frontend-owned-semantic-editor-presentation
title: Frontend-Owned Semantic Presentation Descriptor and Host Consumption
created: 2026-04-02
tags: [studio, editor, frontend, semantic-highlighting, lsp, compiler, pbs, presentation]
---

## Context

The first semantic highlight wave for frontend documents had already proved that Studio could consume semantic spans through the integrated LSP path.
The remaining ownership problem was narrower but important:

- semantic colors for frontend documents were still effectively hosted by Studio,
- the frontend did not publish a first-class semantic presentation contract,
- and the semantic bridge risked collapsing frontend meaning into host-owned categories.

This discussion closed that gap by moving semantic presentation ownership fully to the frontend while keeping Studio and LSP in narrow host roles.

## Key Decisions

### Make `FrontendSpec` the Canonical Semantic Presentation Contract

**What:**
The canonical semantic presentation contract now lives in `FrontendSpec` and carries frontend-owned `semanticKeys` plus frontend-owned `resources` in a single descriptor shape.

**Why:**
Semantic presentation is part of the frontend's meaning, not just an editor skin.
Keeping the contract in `FrontendSpec` lets semantic vocabulary and presentation resources evolve with the frontend itself.

**Trade-offs:**
Frontend metadata becomes slightly richer and must now be kept coherent with shipped resources.
That extra discipline is worth it because it keeps ownership explicit and versionable.

### Keep LSP as a Contract Bridge, Not a Semantic Owner

**What:**
LSP derives a semantic presentation descriptor from the resolved `FrontendSpec` and exposes it to Studio, but it does not own resources and does not translate frontend semantics into host-owned generic buckets.

**Why:**
The LSP layer should bridge analysis products into host consumption, not normalize language identity away.
If LSP emitted categories such as `fe-keyword`, it would pull frontend semantics into the wrong layer.

**Trade-offs:**
DTOs and semantic indexing need to preserve language-owned keys all the way through transport.
That is a better cost than growing a fake shared semantic vocabulary in the host stack.

### Keep Studio Mechanical and Fallback-Free

**What:**
Studio now projects frontend semantic keys mechanically into CSS classes and consumes frontend-owned resources through the descriptor.
If descriptor data or usable resources are absent, Studio simply skips semantic highlight for that frontend document.

**Why:**
Studio owns rendering plumbing and editor UX, not frontend semantics.
Mechanical projection preserves that boundary, and no generic fallback theme avoids silently reintroducing host ownership.

**Trade-offs:**
The host no longer guarantees a semantic color scheme for misconfigured frontend contracts.
That is intentional, because degraded no-highlight behavior is safer than a misleading generic fallback.

## Final Implementation

The final implementation landed across specs, compiler/frontend metadata, LSP transport, and Studio consumption:

- `docs/specs/studio/5. Code Editor Workspace Specification.md` and `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md` now state that frontend semantic presentation is frontend-owned, derived from `FrontendSpec`, and fallback-free.
- `docs/specs/compiler-languages/pbs/README.md` now declares PBS ownership of semantic vocabulary and semantic editor presentation contract.
- `FrontendSpec` is now used as the canonical source of semantic presentation metadata consumed by the editor pipeline.
- `PBSDefinitions` publishes PBS semantic keys and resource paths, and `PbsSemanticKind` defines the stable frontend-owned semantic vocabulary.
- `prometeu-lsp` now transports frontend-owned semantic keys and exposes `LspSemanticPresentationDTO` derived from the resolved frontend spec instead of collapsing highlights into host-owned `fe-*` buckets.
- Studio consumes descriptor resources through `EditorDocumentPresentationRegistry`, projects keys mechanically through `EditorDocumentSemanticHighlighting`, and applies frontend-owned stylesheets such as PBS semantic highlight resources.

## Patterns and Algorithms

### Pattern: Treat Semantic Presentation as Language Metadata

When editor semantic styling is language-specific, the contract should live with the frontend definition rather than with the host renderer.
That keeps vocabulary, resources, and evolution under the same owner.

### Pattern: Bridge Metadata Without Reinterpreting It

The correct transport flow is:

- frontend defines semantic vocabulary and resources,
- LSP derives and transports the descriptor,
- Studio consumes and renders it mechanically.

The bridge must preserve keys, not rename them into a host dialect.

### Example: Mechanical Projection Rule

The resulting projection flow is:

1. PBS publishes a semantic key such as `pbs-function`.
2. LSP returns highlight spans with that same key and a descriptor containing PBS resources.
3. Studio projects the key to `editor-semantic-pbs-function`.
4. PBS-owned stylesheet resources style that class.

## Pitfalls

- Do not reintroduce generic host-owned semantic keys such as `fe-keyword` or `fe-type`.
- Do not move frontend semantic stylesheets back into Studio just because the renderer loads them.
- Do not treat LSP DTO ownership as presentation ownership; transport is not authorship.
- Do not add a generic fallback theme for missing frontend metadata, because that silently restores host semantic ownership.
- Do not make Studio perform deep contract validation that belongs in frontend tests.

## References

- `DEC-0012` Frontend-owned semantic editor presentation via FrontendSpec-derived descriptor
- `PLN-0026` Propagate DEC-0012 into Studio and frontend normative specs
- `PLN-0027` Add frontend semantic presentation contract to FrontendSpec and expose it through LSP
- `PLN-0028` Consume frontend-owned semantic presentation in Studio and retire generic FE theme usage
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `docs/specs/compiler-languages/pbs/README.md`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsSemanticKind.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/LspSemanticPresentationDTO.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`

## Takeaways

- Semantic presentation belongs to the frontend when semantic meaning belongs to the frontend.
- LSP should transport frontend-owned contracts without flattening them into host-owned categories.
- Studio stays cleaner when it renders semantic presentation mechanically and degrades to no highlight instead of inventing a fallback theme.
