prometeu-studio/discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md

id	ticket	title	created	tags
LSN-0029	studio-frontend-owned-semantic-editor-presentation	Frontend-Owned Semantic Presentation Descriptor and Host Consumption	2026-04-02	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.