prometeu-studio/discussion/workflow/decisions/DEC-0012-frontend-owned-semantic-editor-presentation.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0012	studio-frontend-owned-semantic-editor-presentation	Frontend-owned semantic editor presentation via FrontendSpec-derived descriptor	accepted	2026-04-02	2026-04-02	AGD-0015	PLN-0026 PLN-0027 PLN-0028	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.