clean up
This commit is contained in:
+134
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: LSN-0028
|
||||
ticket: studio-editor-write-wave-supported-non-frontend-files
|
||||
title: Controlled Editor Write Wave and Read-Only Frontend Semantic Phase
|
||||
created: 2026-04-02
|
||||
tags: [studio, editor, vfs, lsp, access-policy, save, read-only, frontend-boundary]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The first Studio `Code Editor` implementation had already established a session-owned document boundary through `prometeu-vfs`, but it was still missing the next operational split:
|
||||
|
||||
- which supported files could become editable now,
|
||||
- which files had to remain hard `read-only`,
|
||||
- where save ownership lived,
|
||||
- and how frontend semantic value could ship before frontend editing rights.
|
||||
|
||||
This discussion closed that split in two coordinated decisions.
|
||||
The result is a deliberately mixed editor phase:
|
||||
|
||||
- supported non-frontend textual documents can be edited and saved,
|
||||
- frontend-scoped documents stay hard `read-only`,
|
||||
- and frontend semantic features arrive through `prometeu-lsp` as a consumer of VFS snapshots rather than as a new document owner.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Keep Access Policy and Save Ownership in `prometeu-vfs`
|
||||
|
||||
**What:**
|
||||
`prometeu-vfs` is the canonical owner of document access mode, canonical `typeId`, editable in-memory snapshots, save, and save-all behavior for the first write wave.
|
||||
|
||||
**Why:**
|
||||
The editor workspace needs to consume policy, not recreate it.
|
||||
If editability, frontend classification, or save rules drift into Studio UI code, the product loses the project-document boundary that earlier work had just established.
|
||||
|
||||
**Trade-offs:**
|
||||
This adds explicit VFS contract surface for access context, document mutation, and save orchestration.
|
||||
That extra structure is intentional because it prevents editor-local heuristics from becoming product behavior.
|
||||
|
||||
### Release a Narrow Write Wave Instead of Universal Editing
|
||||
|
||||
**What:**
|
||||
The editable set is intentionally limited to already-supported non-frontend textual classes: `text`, `json`, `ndjson`, and `bash`.
|
||||
Frontend-scoped files stay hard `read-only` in the same workspace.
|
||||
|
||||
**Why:**
|
||||
Not every supported text file belongs to the same product tier.
|
||||
Frontend files carry language-owned semantics and future editing constraints that were not ready to ship in the same wave as generic project documents.
|
||||
|
||||
**Trade-offs:**
|
||||
The editor becomes mixed-mode immediately, which requires clearer UX for save enablement, status-bar access state, and frontend warnings.
|
||||
That is preferable to pretending all supported documents can be treated uniformly.
|
||||
|
||||
### Introduce Frontend Semantic Read Before Frontend Edit Rights
|
||||
|
||||
**What:**
|
||||
`prometeu-lsp` was introduced as a semantic consumer above `prometeu-vfs` for frontend diagnostics, symbols, outline structure, definition, and semantic highlight while frontend files remain hard `read-only`.
|
||||
|
||||
**Why:**
|
||||
Semantic readiness and editing rights should not be released together by default.
|
||||
The semantic-read phase provides real value for frontend files without collapsing access policy, persistence, and semantic analysis into a single owner.
|
||||
|
||||
**Trade-offs:**
|
||||
The system now has one more module boundary and one more contract seam to maintain.
|
||||
That cost is lower than releasing frontend mutation before the semantic substrate and ownership boundaries are stable.
|
||||
|
||||
## Final Implementation
|
||||
|
||||
The final implementation landed across specs, VFS, LSP, and Studio UI:
|
||||
|
||||
- `docs/specs/studio/5. Code Editor Workspace Specification.md` now defines the mixed editable and hard `read-only` editor wave, editor-local `Save` and `Save All`, frontend warning surfaces, and the frontend semantic-read phase.
|
||||
- `docs/specs/studio/6. Project Document VFS Specification.md` now makes `FrontendSpec.allowedExtensions` the source of truth for frontend scope, defines canonical `typeId` and access-mode ownership, and keeps editorial snapshots separate from build-facing state.
|
||||
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md` now defines the minimum frontend semantic-read phase and the flat public packaging expectations for `prometeu-lsp`.
|
||||
- `FilesystemVfsProjectDocument` classifies supported documents as editable or hard `read-only`, keeps editable in-memory snapshots, rejects mutation for hard `read-only` frontend documents, and persists editable snapshots through save operations.
|
||||
- `prometeu-lsp` now exposes a concrete semantic-read service layer for diagnostics, symbols, definition, and frontend highlight consumption over VFS-backed session state.
|
||||
- `EditorWorkspace`, `EditorOpenFileSession`, `EditorStatusBar`, and related UI surfaces now consume VFS access policy, expose editor-local save actions, and render mixed editable and frontend `read-only` tabs coherently.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Pattern: Make the Editor a Policy Consumer
|
||||
|
||||
The correct ownership split is:
|
||||
|
||||
- `prometeu-vfs` decides supported document classification, access mode, snapshot ownership, and save behavior;
|
||||
- `prometeu-lsp` consumes VFS-backed document state for semantic analysis;
|
||||
- Studio UI consumes both boundaries for presentation and interaction.
|
||||
|
||||
This keeps each layer honest about its owner role.
|
||||
|
||||
### Pattern: Ship Semantic Value Before Edit Rights
|
||||
|
||||
When language-owned files need semantic support before mutation support, introduce a semantic-read phase instead of unlocking editing prematurely.
|
||||
That pattern gives diagnostics, navigation, and semantic presentation without forcing save, dirty tracking, or mutation policy into a half-ready frontend phase.
|
||||
|
||||
### Example: Mixed-Mode Editor Flow
|
||||
|
||||
The resulting flow is:
|
||||
|
||||
1. `prometeu-vfs` opens a supported document and returns canonical `typeId` plus access context.
|
||||
2. Studio opens the tab and renders editable or hard `read-only` state from that policy.
|
||||
3. Editable non-frontend documents mutate session-owned snapshots and save through editor-local actions.
|
||||
4. Frontend documents remain non-mutable, show explicit warning and status surfaces, and may still receive semantic diagnostics, symbols, definition, and highlight through `prometeu-lsp`.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Do not let Studio UI re-derive frontend scope from file extensions or path heuristics; `FrontendSpec.allowedExtensions` must stay behind the VFS boundary.
|
||||
- Do not treat editorial in-memory snapshots as canonical build input just because LSP can analyze them.
|
||||
- Do not let `prometeu-lsp` absorb save, persistence, or access-policy ownership.
|
||||
- Do not silently expand editable scope beyond `text`, `json`, `ndjson`, and `bash` without a new explicit decision.
|
||||
- Do not release frontend editing just because frontend semantic highlight and definition already exist.
|
||||
|
||||
## References
|
||||
|
||||
- `DEC-0010` Establish the controlled non-frontend editor write wave in Studio
|
||||
- `DEC-0011` Establish the frontend read-only minimum LSP phase in Studio
|
||||
- `PLN-0019` Propagate DEC-0010 into Studio editor and VFS specs
|
||||
- `PLN-0020` Build DEC-0010 VFS access policy and save core
|
||||
- `PLN-0021` Integrate DEC-0010 editor write UI and workflow in Studio
|
||||
- `PLN-0022` Propagate DEC-0011 into Studio, VFS, and LSP specs
|
||||
- `PLN-0023` Scaffold flat-packed prometeu-lsp API and Studio session seams
|
||||
- `PLN-0024` Implement read-only FE diagnostics, symbols, and definition over VFS snapshots
|
||||
- `PLN-0025` Implement FE semantic highlight and editor consumption for the read-only LSP phase
|
||||
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
|
||||
- `docs/specs/studio/6. Project Document VFS Specification.md`
|
||||
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
|
||||
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemVfsProjectDocument.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspServiceImpl.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
|
||||
|
||||
## Takeaways
|
||||
|
||||
- A mixed editable plus hard `read-only` editor wave is viable when access policy stays centralized in VFS.
|
||||
- Semantic-read support is a separate product phase from frontend edit rights and should be modeled that way.
|
||||
- Save ownership, semantic consumption, and UI presentation stay cleaner when `prometeu-vfs`, `prometeu-lsp`, and Studio each keep a narrow role.
|
||||
+127
@@ -0,0 +1,127 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user