FE highlight ownership

This commit is contained in:
2026-04-02 15:03:00 +01:00
parent aab3059ac7
commit c00fc221be
6 changed files with 751 additions and 1 deletions
@@ -0,0 +1,113 @@
---
id: PLN-0026
ticket: studio-frontend-owned-semantic-editor-presentation
title: Propagate DEC-0012 into Studio and frontend normative specs
status: review
created: 2026-04-02
completed:
tags:
- studio
- editor
- frontend
- specs
- semantic-highlighting
---
## Objective
Propagate `DEC-0012` into the normative documentation surfaces that define semantic editor presentation ownership, contract source, and runtime fallback behavior.
## Background
`DEC-0012` locks a new ownership model:
- frontend owns semantic vocabulary;
- frontend owns semantic presentation resources;
- `FrontendSpec` is the canonical source of the semantic presentation contract;
- LSP derives a descriptor from `FrontendSpec`;
- Studio consumes the descriptor without semantic reinterpretation;
- missing descriptor or resources degrade to no semantic highlight.
These rules must be reflected in the Studio and frontend-facing specs before implementation work proceeds.
## Scope
### Included
- Studio editor specification updates for frontend-owned semantic presentation.
- LSP semantic read phase specification updates for descriptor bridging behavior.
- Compiler/frontend specification updates that place semantic presentation contract ownership in `FrontendSpec`.
- Documentation of the runtime behavior `no contract/resource -> no highlight`.
### Excluded
- Java implementation changes.
- FE resource creation or stylesheet migration.
- Test implementation.
## Execution Steps
### Step 1 - Update Studio semantic editor ownership rules
**What:**
Update Studio specs so the editor is no longer the owner of a generic frontend semantic theme.
**How:**
Amend the Code Editor and related Studio specs to state that Studio hosts rendering only, consumes a frontend-owned descriptor, and applies no generic fallback theme.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
### Step 2 - Update frontend contract ownership rules
**What:**
Document that frontend semantic presentation contract data lives in `FrontendSpec`.
**How:**
Amend compiler/frontend spec surfaces to describe `semanticKeys + resources` as frontend-owned static contract data published through `FrontendSpec`.
**File(s):**
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
- `docs/specs/compiler-languages/pbs/README.md`
- any more specific frontend spec file that currently owns frontend metadata publication semantics
### Step 3 - Lock runtime degradation behavior in spec text
**What:**
Specify the runtime behavior when semantic presentation contract data or resources are absent.
**How:**
State normatively that Studio must continue without semantic highlight, must not surface a product-facing UI error, and may only emit normal development logs.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
## Test Requirements
### Unit Tests
- No code tests in this plan.
### Integration Tests
- No runtime tests in this plan.
### Manual Verification
- Review updated spec text against every normative clause in `DEC-0012`.
- Verify no spec reintroduces a Studio-owned generic frontend theme.
## Acceptance Criteria
- [ ] Studio specs state that semantic presentation is frontend-owned.
- [ ] Specs name `FrontendSpec` as the canonical contract source.
- [ ] Specs describe the descriptor shape at a high level as `semanticKeys + resources`.
- [ ] Specs define `no contract/resource -> no highlight`.
- [ ] Specs define that no generic Studio fallback theme is allowed.
## Dependencies
- Depends on `DEC-0012`.
- Should complete before or in parallel with implementation plans so implementation follows normative text.
## Risks
- Existing spec text may still imply Studio ownership of generic frontend presentation.
- Compiler spec propagation may be underspecified if the exact frontend metadata sections are spread across multiple files.
@@ -0,0 +1,139 @@
---
id: PLN-0027
ticket: studio-frontend-owned-semantic-editor-presentation
title: Add frontend semantic presentation contract to FrontendSpec and expose it through LSP
status: review
created: 2026-04-02
completed:
tags:
- compiler
- frontend
- lsp
- contract
- semantic-highlighting
---
## Objective
Implement the frontend-owned semantic presentation contract in `FrontendSpec` and expose a derived descriptor through LSP without collapsing frontend semantics into host-owned categories.
## Background
`DEC-0012` requires:
- static contract data in `FrontendSpec`;
- a simple descriptor containing `semanticKeys + resources`;
- frontend-owned semantic vocabulary using stable `semanticKey` values;
- LSP as a hub that derives and exposes the descriptor to Studio;
- no generic semantic-key reduction such as `fe-keyword`.
## Scope
### Included
- `FrontendSpec` contract model additions.
- FE-specific publication of semantic keys and semantic presentation resources.
- Replacement of generic LSP semantic key emission with frontend-owned keys.
- LSP descriptor derivation and API exposure.
- FE-side tests covering contract presence and consistency.
### Excluded
- Studio CSS application changes.
- Studio presentation registry migration.
- Removal of legacy Studio stylesheets, except where required to avoid compile/runtime conflicts.
## Execution Steps
### Step 1 - Extend FrontendSpec with semantic presentation contract
**What:**
Add a static semantic presentation contract to `FrontendSpec`.
**How:**
Introduce a dedicated descriptor type that carries frontend-owned `semanticKeys + resources`, wire it into `FrontendSpec`, and keep `FrontendSpec` static and frontend-owned.
**File(s):**
- `prometeu-compiler/prometeu-frontend-api/src/main/java/.../FrontendSpec.java`
- any adjacent model files needed for the new descriptor type
### Step 2 - Publish PBS semantic vocabulary and resources through FrontendSpec
**What:**
Make PBS publish frontend-owned semantic keys and highlight resources.
**How:**
Add a frontend-owned semantic vocabulary model such as `PbsSemanticKind -> semanticKey`, publish the resulting semantic presentation contract from PBS frontend definitions, and point the descriptor to FE-owned resources.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/PBSDefinitions.java`
- PBS semantic analysis/indexing files that currently assign generic `fe-*` categories
- FE resource directory under the PBS frontend module
### Step 3 - Remove generic semantic key collapse in LSP
**What:**
Stop translating frontend semantics into host-owned generic semantic keys.
**How:**
Replace `fe-keyword`, `fe-type`, and similar outputs with frontend-owned semantic keys coming from frontend semantic vocabulary and/or `FrontendSpec` contract data.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
- any LSP DTO/message models that need to surface the descriptor
### Step 4 - Expose descriptor from analysis to Studio-facing LSP results
**What:**
Expose a Studio-consumable descriptor derived from the resolved `FrontendSpec`.
**How:**
Derive the descriptor during analysis/session creation and include it in the LSP surface that Studio consumes for semantic highlight application.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/...` messages/DTOs
- any semantic session models involved in transport
### Step 5 - Add FE contract tests
**What:**
Verify the FE contract is present and coherent.
**How:**
Add frontend tests that fail when semantic presentation contract data is missing, when semantic keys are not published, or when published resources do not match the FE contract shape expectations.
**File(s):**
- PBS frontend tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...`
- frontend-api tests if `FrontendSpec` invariants are enforced there
## Test Requirements
### Unit Tests
- `FrontendSpec` tests for semantic presentation descriptor presence and shape.
- PBS frontend tests for semantic key publication.
- LSP tests for transport of frontend-owned semantic keys and descriptor data.
### Integration Tests
- Analyze a PBS file through LSP and assert that returned semantic highlights use PBS-owned semantic keys.
- Assert that the descriptor surfaced to the consumer contains the expected `semanticKeys + resources`.
### Manual Verification
- Inspect LSP payloads/logs to confirm there is no remaining `fe-*` semantic key collapse for PBS.
## Acceptance Criteria
- [ ] `FrontendSpec` exposes a static semantic presentation contract.
- [ ] PBS publishes semantic keys and resources through that contract.
- [ ] LSP no longer emits generic host-owned semantic keys for PBS.
- [ ] LSP exposes a descriptor derived from resolved `FrontendSpec`.
- [ ] FE tests cover missing contract data and contract consistency.
## Dependencies
- Depends on `DEC-0012`.
- Should land before Studio consumption changes in `PLN-0028`.
## Risks
- Existing semantic indexing code is currently host-owned and may require a larger refactor than expected.
- DTO surface changes can ripple through Studio and tests.
- Resource publication conventions may be inconsistent across future frontends if not modeled cleanly now.
@@ -0,0 +1,132 @@
---
id: PLN-0028
ticket: studio-frontend-owned-semantic-editor-presentation
title: Consume frontend-owned semantic presentation in Studio and retire generic FE theme usage
status: review
created: 2026-04-02
completed:
tags:
- studio
- editor
- semantic-highlighting
- frontend
- presentation
---
## Objective
Make Studio consume the frontend-owned semantic presentation descriptor from LSP, apply FE-owned resources, and degrade cleanly to no highlight when semantic presentation data is unavailable.
## Background
`DEC-0012` and `PLN-0027` move semantic presentation ownership out of Studio. After the descriptor and frontend resources exist, Studio must stop relying on generic frontend presentation styling and instead consume FE-owned semantic presentation data.
## Scope
### Included
- Studio-side consumption of the LSP semantic presentation descriptor.
- Mechanical semantic key to CSS class projection.
- Loading FE-owned highlight resources through normal Java resource resolution.
- Graceful no-highlight behavior when descriptor/resources are unavailable.
- Removal of generic FE-specific highlight ownership assumptions from Studio runtime flow.
### Excluded
- Frontend contract creation.
- LSP descriptor creation.
- Spec writing.
## Execution Steps
### Step 1 - Add descriptor-aware Studio highlight consumption
**What:**
Teach Studio editor highlighting flow to consume the frontend semantic presentation descriptor.
**How:**
Extend the Studio-side LSP consumption path so semantic highlight application depends on descriptor data and no longer assumes a single generic frontend presentation.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`
### Step 2 - Replace generic FE styling assumption with mechanical class projection
**What:**
Project frontend semantic keys directly into CSS classes.
**How:**
Implement a stable Studio-side projection rule such as `semanticKey -> editor-semantic-<semanticKey>` and apply those classes to semantic spans without any semantic translation layer.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/syntaxhighlight/EditorDocumentSemanticHighlighting.java`
- any adjacent presentation/style support files
### Step 3 - Load FE-owned resources and remove generic FE ownership path
**What:**
Load FE-owned stylesheet resources rather than Studio-owned generic FE semantic CSS.
**How:**
Use descriptor resources surfaced through LSP, attach the referenced stylesheet(s) to the editor presentation/runtime flow, and stop depending on generic `fe.css` as the semantic owner for FE documents.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentPresentationRegistry.java`
- `prometeu-studio/src/main/resources/themes/editor/presentations/fe.css` if retired or narrowed
### Step 4 - Implement graceful no-highlight degradation
**What:**
Ensure Studio continues to work without semantic highlight when descriptor/resources are absent.
**How:**
When the descriptor is absent or resources cannot be consumed, skip semantic styling for that frontend document, preserve editor usability, and avoid user-facing Studio errors.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- semantic highlight routing/presentation files in the editor workspace
### Step 5 - Add Studio tests for FE-owned semantic presentation consumption
**What:**
Cover descriptor consumption, class projection, and no-highlight degradation.
**How:**
Add editor-side tests that assert Studio consumes descriptor data, applies projected classes, and keeps operating when descriptor/resources are missing.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/...`
## Test Requirements
### Unit Tests
- Editor highlight routing tests for semantic key projection.
- Presentation registry tests for descriptor-driven resource loading.
- No-highlight degradation tests when descriptor/resources are absent.
### Integration Tests
- End-to-end Studio/LSP test using a frontend document with FE-owned semantic keys and FE-owned stylesheet resources.
### Manual Verification
- Open a PBS document and verify semantic colors come from FE-owned presentation resources, not generic Studio FE theme assumptions.
- Temporarily remove or break the descriptor/resource and verify the editor remains usable with no semantic highlight.
## Acceptance Criteria
- [ ] Studio consumes frontend-owned semantic presentation descriptor data from LSP.
- [ ] Studio projects semantic keys mechanically to CSS classes.
- [ ] Generic Studio-owned frontend semantic presentation is no longer the runtime owner for FE highlight.
- [ ] Missing descriptor/resources degrade to no highlight without Studio UI errors.
- [ ] Studio tests cover the new descriptor consumption path.
## Dependencies
- Depends on `DEC-0012`.
- Depends on `PLN-0027` for descriptor and resource publication.
- Can run after or in parallel with `PLN-0026`, but should not merge before the contract surface in `PLN-0027` exists.
## Risks
- Existing Studio presentation registry may assume static local stylesheets and need a broader refactor.
- Descriptor-driven resource loading can accidentally leak stylesheet accumulation if lifecycle cleanup is not handled carefully.
- Partial migration may leave residual `fe.css` assumptions in tests or runtime paths.