128 lines
7.1 KiB
Markdown
128 lines
7.1 KiB
Markdown
---
|
|
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.
|