FE highlight ownership
This commit is contained in:
+113
@@ -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.
|
||||
+139
@@ -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.
|
||||
+132
@@ -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.
|
||||
Reference in New Issue
Block a user