156 lines
7.5 KiB
Markdown
156 lines
7.5 KiB
Markdown
---
|
|
id: DEC-0011
|
|
ticket: studio-editor-write-wave-supported-non-frontend-files
|
|
title: Establish the frontend read-only minimum LSP phase in Studio
|
|
status: accepted
|
|
created: 2026-03-31
|
|
accepted: 2026-03-31
|
|
agenda: AGD-0014
|
|
plans:
|
|
- PLN-0022
|
|
- PLN-0023
|
|
- PLN-0024
|
|
- PLN-0025
|
|
tags:
|
|
- studio
|
|
- editor
|
|
- workspace
|
|
- frontend-boundary
|
|
- lsp
|
|
- access-policy
|
|
---
|
|
|
|
## Context
|
|
|
|
The controlled non-frontend write wave intentionally kept frontend-scoped documents `read-only`.
|
|
|
|
After that closure, the next question was not "how to edit frontend now", but rather:
|
|
|
|
- whether Studio could already gain semantic value over frontend documents while they remain `read-only`,
|
|
- how `prometeu-lsp` should relate to `prometeu-vfs`,
|
|
- what minimum semantic scope is worth shipping,
|
|
- and how to keep this phase separate from the later decision that may release frontend editing.
|
|
|
|
The accepted agenda closed that this phase should remain explicitly `read-only` for frontend documents while introducing a minimum integrated LSP layer over the same project-session document substrate.
|
|
|
|
## Decision
|
|
|
|
1. Studio SHALL introduce a frontend `read-only` semantic phase before any frontend editing phase is considered.
|
|
2. This phase SHALL keep frontend-scoped documents hard `read-only`.
|
|
3. This phase SHALL introduce a minimum integrated `prometeu-lsp` consumer above `prometeu-vfs`.
|
|
4. `prometeu-lsp` SHALL consume document state exposed by `prometeu-vfs`.
|
|
5. For opened frontend documents, `prometeu-lsp` SHALL analyze the in-memory session snapshot exposed by `prometeu-vfs`.
|
|
6. For unopened frontend documents, `prometeu-lsp` MAY fall back to filesystem-backed state exposed through the same document boundary.
|
|
7. `prometeu-lsp` MUST NOT become the owner of document persistence, save policy, or access policy.
|
|
8. `prometeu-vfs` SHALL remain the owner of document state, snapshots, persistence, and access-policy context.
|
|
9. Frontend scope in this phase SHALL continue to use `FrontendSpec.allowedExtensions` as source of truth, and the VFS contract SHALL expose a frontend-compatible canonical `typeId` or equivalent scope marker derived from that source of truth.
|
|
10. The minimum semantic scope of this phase SHALL include:
|
|
- diagnostics,
|
|
- document symbols and workspace symbols,
|
|
- outline-facing structural symbol data,
|
|
- definition,
|
|
- highlight for frontend documents.
|
|
11. Highlight for non-frontend documents MAY remain Studio-local as currently implemented in this phase.
|
|
12. Highlight for frontend documents SHALL come from semantic information provided through `prometeu-lsp` and SHALL use frontend-owned color semantics rather than a Studio-local fallback scheme.
|
|
13. `Completion` SHALL remain out of scope for this minimum `read-only` phase.
|
|
14. `Rename`, code actions, formatting, and any frontend edit-right release SHALL remain out of scope for this phase.
|
|
15. The future release of frontend editing SHALL be handled by a separate discussion and decision.
|
|
16. The editorial in-memory state observed by `prometeu-lsp` MAY feed semantic analysis, but MUST NOT be treated as canonical build input by implication.
|
|
17. Any future bridge between frontend editorial state and build-facing state SHALL require a separate explicit decision.
|
|
18. `prometeu-lsp` API organization SHALL prefer flat packaging modeled after `prometeu-packer-api`, using explicit public surfaces such as `dtos`, `messages`, and `events` where appropriate.
|
|
19. `prometeu-vfs` does not need to persist document-access context yet, but it SHALL introduce a single context entity for such values so that read, mutation, and future persistence remain a natural extension rather than a redesign.
|
|
|
|
## Rationale
|
|
|
|
This decision separates semantic readiness from editing rights.
|
|
|
|
That separation is valuable because frontend files are materially different from generic textual documents.
|
|
For frontend documents, even a minimum Studio-integrated semantic consumer provides immediate value:
|
|
|
|
- diagnostics,
|
|
- outline and symbols,
|
|
- definition,
|
|
- highlight,
|
|
- and a validated path from document session state into semantic reading.
|
|
|
|
At the same time, keeping editing out of this phase protects the product from releasing mutation before its semantic consumer and editorial boundaries are ready.
|
|
|
|
The decision also preserves a clean ownership model:
|
|
|
|
- `prometeu-vfs` owns document state,
|
|
- `prometeu-lsp` consumes that state,
|
|
- the editor owns UX,
|
|
- and build remains separate.
|
|
|
|
## Technical Specification
|
|
|
|
### 1. Phase Boundary
|
|
|
|
- This decision defines a frontend semantic-read phase, not a frontend editing phase.
|
|
- Frontend documents remain hard `read-only` throughout this decision's scope.
|
|
- No plan derived from this decision may infer `save`, mutation, or frontend dirty-tracking rights.
|
|
|
|
### 2. Document Source of Truth for Analysis
|
|
|
|
- Opened frontend documents MUST be analyzed from the in-memory document snapshot held by `prometeu-vfs`.
|
|
- Closed frontend documents MAY be analyzed from filesystem-backed document state through the same boundary.
|
|
- Frontend scope MUST continue to derive from `FrontendSpec.allowedExtensions`.
|
|
- The VFS contract MUST expose a frontend-compatible canonical `typeId` or equivalent scope marker derived from that source of truth.
|
|
- Consumers MUST NOT bypass `prometeu-vfs` with ad hoc file loading inside Studio UI code.
|
|
|
|
### 3. Minimum LSP Capability Set
|
|
|
|
- The minimum phase MUST provide:
|
|
- diagnostics,
|
|
- document symbols,
|
|
- workspace symbols,
|
|
- outline-facing symbol structure,
|
|
- go-to-definition,
|
|
- frontend highlight.
|
|
- `Completion` is explicitly excluded from this minimum phase.
|
|
- Highlight for non-frontend files may remain Studio-local during this phase.
|
|
- Highlight for frontend files MUST come from LSP semantic output and frontend-owned color semantics.
|
|
|
|
### 4. Ownership Rules
|
|
|
|
- `prometeu-lsp` MUST remain a semantic consumer.
|
|
- `prometeu-lsp` MUST NOT own:
|
|
- save,
|
|
- persistence,
|
|
- document access policy,
|
|
- frontend edit-right release.
|
|
- `prometeu-vfs` MUST remain the owner of document state and access context.
|
|
|
|
### 5. Packaging Rules
|
|
|
|
- The public API of `prometeu-lsp` SHOULD use flat packaging similar to `prometeu-packer-api`.
|
|
- Public contract types SHOULD be grouped under explicit, shallow package surfaces such as:
|
|
- `dtos`
|
|
- `messages`
|
|
- `events`
|
|
- Deep packaging by internal implementation concern SHOULD be avoided for public contract surfaces.
|
|
|
|
### 6. Context Reservation
|
|
|
|
- `prometeu-vfs` MUST introduce a single context entity for document-access-related values that may evolve later.
|
|
- This context does not need persistence yet.
|
|
- It MUST already support lookup and mutation under current demand so that future persistence can be added without reworking the model.
|
|
|
|
### 7. Boundary with Build
|
|
|
|
- Semantic analysis over editorial in-memory state does not authorize build participation.
|
|
- No implementation derived from this decision may treat editorial snapshots as canonical build inputs.
|
|
- Build-facing transitions require separate decision work.
|
|
|
|
## Constraints
|
|
|
|
- This decision does not release frontend editing.
|
|
- This decision does not authorize completion.
|
|
- This decision does not authorize semantic gating of save because save for frontend files remains out of scope.
|
|
- This decision does not authorize external-editor compatibility requirements.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-03-31: Initial accepted decision from AGD-0014.
|
|
- 2026-03-31: Clarified frontend scope source-of-truth via `FrontendSpec.allowedExtensions`, hardened frontend read-only semantics, and locked frontend highlight to LSP semantic output while non-frontend highlight remains Studio-local.
|