143 lines
6.1 KiB
Markdown
143 lines
6.1 KiB
Markdown
---
|
|
id: DEC-0012
|
|
ticket: studio-frontend-owned-semantic-editor-presentation
|
|
title: Frontend-owned semantic editor presentation via FrontendSpec-derived descriptor
|
|
status: accepted
|
|
created: 2026-04-02
|
|
accepted: 2026-04-02
|
|
agenda: AGD-0015
|
|
plans:
|
|
- PLN-0026
|
|
- PLN-0027
|
|
- PLN-0028
|
|
tags:
|
|
- studio
|
|
- editor
|
|
- frontend
|
|
- presentation
|
|
- semantic-highlighting
|
|
- compiler
|
|
- pbs
|
|
---
|
|
|
|
## Decision
|
|
|
|
The semantic editor presentation for frontend documents SHALL be frontend-owned.
|
|
|
|
Normative decision:
|
|
|
|
1. Each frontend MUST publish its own semantic vocabulary.
|
|
2. Each frontend MUST publish its own semantic highlight resources.
|
|
3. Neither Studio nor LSP SHALL own frontend semantic presentation assets.
|
|
4. The canonical source of this contract MUST live in `FrontendSpec`.
|
|
5. LSP MUST act only as a hub/contract bridge between frontend metadata and Studio consumption.
|
|
6. LSP MUST NOT reduce frontend semantics into a shared artificial vocabulary such as `fe-keyword`, `fe-type`, or equivalent host-owned categories.
|
|
7. Studio MUST consume the frontend semantic presentation contract without reinterpreting frontend semantics.
|
|
8. Studio MUST project semantic keys to CSS classes mechanically, without semantic translation tables.
|
|
9. If semantic presentation metadata or usable resources are absent at runtime, Studio SHALL not apply semantic highlight for that frontend document.
|
|
10. Studio MUST NOT replace missing frontend presentation with a generic host-owned fallback theme.
|
|
|
|
## Rationale
|
|
|
|
The prior arrangement centralized frontend semantic colors in Studio under a generic `fe.css` presentation. That arrangement was acceptable as an early integration shortcut, but it violates the intended boundary of a multi-frontend editor:
|
|
|
|
- Studio owns rendering surfaces and editor UX.
|
|
- The frontend owns semantic meaning.
|
|
- Semantic presentation is part of that frontend-owned meaning.
|
|
|
|
If Studio remains the owner of semantic presentation, every additional frontend either:
|
|
|
|
- collapses into a weak common denominator,
|
|
- negotiates language-specific editorial rules inside the host,
|
|
- or forces Studio to accumulate language-owned semantics.
|
|
|
|
That is the wrong ownership direction.
|
|
|
|
LSP is also not the correct owner. Its role in this design is to bridge frontend analysis products into host consumption, not to normalize, reinterpret, or host language assets.
|
|
|
|
This decision therefore locks the boundary as follows:
|
|
|
|
- frontend owns semantic vocabulary,
|
|
- frontend owns semantic presentation assets,
|
|
- `FrontendSpec` is the canonical contract source,
|
|
- LSP derives and transports a consumable descriptor,
|
|
- Studio renders what the frontend publishes.
|
|
|
|
## Technical Specification
|
|
|
|
### 1. Canonical Contract Source
|
|
|
|
1. `FrontendSpec` MUST carry the semantic presentation contract.
|
|
2. `FrontendSpec` SHALL remain a static specification surface.
|
|
3. The semantic presentation contract MUST be frontend-owned and versionable together with the frontend.
|
|
|
|
### 2. Contract Shape
|
|
|
|
The initial semantic presentation contract MUST remain simple but complete.
|
|
|
|
It SHALL include, at minimum:
|
|
|
|
1. `semanticKeys`
|
|
2. `resources`
|
|
|
|
These fields MUST be carried inside a single descriptor/message so the contract can evolve without scattering related presentation metadata across multiple unrelated surfaces.
|
|
|
|
At minimum:
|
|
|
|
- `semanticKeys` defines the frontend-owned stable semantic keys consumable by the editor pipeline.
|
|
- `resources` defines the frontend-owned presentation resources, including the stylesheet resource used for semantic highlight.
|
|
|
|
### 3. Frontend Semantic Vocabulary
|
|
|
|
1. Semantic keys MUST be produced from a frontend-owned semantic vocabulary, for example `SemanticKind -> semanticKey`.
|
|
2. A semantic key MUST be stable enough to serve as contract output.
|
|
3. The name of this contract field SHOULD be `semanticKey`, not `cssKey`, because the key is not owned by CSS and may serve multiple consumers.
|
|
|
|
### 4. LSP Responsibility
|
|
|
|
1. LSP MUST derive a semantic presentation descriptor from the `FrontendSpec` resolved during analysis.
|
|
2. LSP MUST expose that descriptor to Studio.
|
|
3. LSP MUST NOT translate frontend semantic keys into host-owned generic categories.
|
|
4. LSP MUST NOT become the owner of frontend stylesheets or semantic resources.
|
|
|
|
### 5. Studio Responsibility
|
|
|
|
1. Studio MUST remain the owner of rendering, style application, and editor UI plumbing.
|
|
2. Studio MUST NOT define frontend semantic vocabulary.
|
|
3. Studio MUST map semantic keys into CSS classes mechanically.
|
|
4. That mapping MUST be syntactic only, not semantic.
|
|
|
|
Illustrative direction:
|
|
|
|
- frontend semantic key: `pbs-function`
|
|
- Studio-applied class: `editor-semantic-pbs-function`
|
|
|
|
The exact class projection convention MAY be specified later, but the projection MUST remain mechanical and MUST NOT introduce host-owned semantic translation.
|
|
|
|
### 6. Resource Ownership and Resolution
|
|
|
|
1. Frontend semantic presentation resources MUST live under the frontend's own `resources/` surface.
|
|
2. These resources MUST be resolved like ordinary Java resources.
|
|
3. Studio and LSP MUST consume these resources through the contract and MUST NOT duplicate or host them as owners.
|
|
|
|
### 7. Validation and Runtime Behavior
|
|
|
|
1. Deep runtime validation in Studio is NOT required.
|
|
2. Frontend teams SHOULD cover semantic presentation publication with frontend tests.
|
|
3. If descriptor data is present and resources are usable, Studio SHOULD apply semantic highlight.
|
|
4. If descriptor data is absent or resources are unusable, Studio SHALL continue without semantic highlight.
|
|
5. This condition MUST NOT surface as a product-facing Studio error.
|
|
6. At most, normal development logs MAY record the condition.
|
|
|
|
## Constraints
|
|
|
|
1. This decision does NOT change FE edit rights.
|
|
2. This decision does NOT revise `DEC-0011`; it refines ownership and contract shape for semantic presentation only.
|
|
3. This decision MUST NOT be implemented by reintroducing a generic host-owned `fe.css` fallback.
|
|
4. This decision MUST NOT be implemented by collapsing language semantics into generic host-owned semantic buckets.
|
|
5. Any future expansion of the descriptor MUST preserve frontend ownership and the single-descriptor principle established here.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-04-02: Initial accepted decision from AGD-0015.
|