147 lines
6.6 KiB
Markdown
147 lines
6.6 KiB
Markdown
---
|
|
id: LSN-0026
|
|
ticket: studio-code-editor-workspace-foundations
|
|
title: Read-Only Editor Foundations and Semantic Deferral
|
|
created: 2026-03-31
|
|
tags: [studio, editor, workspace, read-only, navigator, tabs, lsp-deferred, ui-foundations]
|
|
---
|
|
|
|
## Context
|
|
|
|
Studio needed a real `Code Editor` workspace, but the team explicitly did not want the first wave to collapse UI structure, file management, write behavior, and language semantics into one premature implementation.
|
|
|
|
The discussion closed a narrower and more durable target:
|
|
|
|
- Studio owns the editorial workspace shell.
|
|
- The first wave is read-only.
|
|
- The workspace must still be useful enough to navigate a full project and open files.
|
|
- Semantic behavior such as diagnostics, symbols, completion, or other LSP-like surfaces must remain deferred.
|
|
|
|
This turned the problem from "build an editor" into "stabilize the workspace composition and file-management shell without hardcoding semantic ownership too early."
|
|
|
|
## Key Decisions
|
|
|
|
### Treat the First Editor Wave as an Editorial Shell, Not a Language Tool
|
|
|
|
**What:**
|
|
The first `Code Editor` wave is a Studio-owned read-only workspace foundation with:
|
|
|
|
- `Project Navigator`
|
|
- reserved `Outline` region
|
|
- responsive tab strip
|
|
- central read-only editor surface
|
|
- passive helper region
|
|
- passive status bar
|
|
|
|
**Why:**
|
|
The workspace needed to become structurally real before it could safely host future semantic providers.
|
|
By freezing the editorial shell first, the team avoided inventing incomplete semantic behavior just to justify the layout.
|
|
|
|
**Trade-offs:**
|
|
The result is intentionally incomplete as an editor.
|
|
It opens files and manages workspace composition, but it does not yet save, mark dirty state, or provide language-aware interactions.
|
|
|
|
### Separate Structural Project State from Open-Document Content State
|
|
|
|
**What:**
|
|
The final implementation keeps two different kinds of in-memory state:
|
|
|
|
- a structural project-tree snapshot for navigation and visual state
|
|
- read-only file buffers only for opened files
|
|
|
|
**Why:**
|
|
These are different responsibilities.
|
|
The navigator needs fast structural state over the whole project, while the editor only needs content snapshots for documents the user has actually opened.
|
|
|
|
**Trade-offs:**
|
|
This adds a small amount of model code up front, but it keeps the workspace testable and prevents the navigator from degenerating into ad hoc filesystem reads during rendering.
|
|
|
|
### Keep Semantic Ownership Deferred but Architectural Seams Open
|
|
|
|
**What:**
|
|
The workspace now reserves real regions for future semantic surfaces such as `Outline`, helper features, and later LSP-backed integrations, but those surfaces remain passive in this wave.
|
|
|
|
**Why:**
|
|
The important rule was not to "solve LSP later" by ignoring layout now.
|
|
The rule was to reserve the correct shell surfaces now without pretending semantic capability already exists.
|
|
|
|
**Trade-offs:**
|
|
The first implementation includes visible placeholders and passive chrome.
|
|
That can feel sparse, but it prevents later layout churn and keeps ownership boundaries explicit.
|
|
|
|
## Final Implementation
|
|
|
|
The Studio domain now has a dedicated `Code Editor` workspace specification and a concrete read-only implementation:
|
|
|
|
- `docs/specs/studio/5. Code Editor Workspace Specification.md` defines the normative first-wave contract.
|
|
- `EditorWorkspace` now mounts a left navigator column, reserved `Outline`, responsive tabs, read-only code area, helper region, and status bar.
|
|
- `EditorProjectSnapshotService` builds a full-project structural tree, including hidden files, folder-first ordering, alphabetical sorting, and frontend-root tagging from `prometeu.json`.
|
|
- `EditorOpenFileSession` keeps opened tabs session-local and read-only.
|
|
- unsupported or non-text files trigger an explicit modal instead of a fake preview.
|
|
- the navigator and status bar share a consistent visual language for folders, source roots, build directories, and `prometeu.json`.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
### Pattern: Stabilize Workspace Chrome Before Semantic Capability
|
|
|
|
When a new workspace will eventually host rich language tooling, first define and implement:
|
|
|
|
1. shell composition
|
|
2. project navigation
|
|
3. document opening model
|
|
4. session-local view state
|
|
5. passive reserved regions for future semantic consumers
|
|
|
|
Only after those are stable should the team decide how semantic providers plug into the shell.
|
|
|
|
### Pattern: Make Read-Only a Deliberate First-Wave Contract
|
|
|
|
Read-only mode is not just a shortcut.
|
|
It is a way to avoid accidentally committing to:
|
|
|
|
- save semantics
|
|
- dirty tracking semantics
|
|
- conflict resolution UX
|
|
- write affordances
|
|
- or editor-to-filesystem mutation rules
|
|
|
|
until those deserve their own discussion.
|
|
|
|
### Pattern: Use Full-Project Visibility with Frontend-Aware Tagging
|
|
|
|
The navigator should not hide non-source files just because the selected frontend only cares about some roots.
|
|
A better pattern is:
|
|
|
|
- show the whole project
|
|
- tag the frontend-relevant roots
|
|
- and keep the filesystem as the source of truth
|
|
|
|
This preserves workspace usability without confusing project ownership with compiler ownership.
|
|
|
|
## Pitfalls
|
|
|
|
- Do not let passive first-wave regions start pretending they are semantic features.
|
|
- Do not reintroduce save or dirty indicators without an explicit decision revision.
|
|
- Do not make the navigator a filtered "source-only" view when the workspace is supposed to expose the real project.
|
|
- Do not collapse structural snapshot state and open-document content buffers into one model.
|
|
- Do not let visual polish quietly smuggle new product behavior into a read-only wave.
|
|
|
|
## References
|
|
|
|
- `DEC-0008` Read-only foundations for the Studio Code Editor workspace
|
|
- `PLN-0012` Propagate DEC-0008 into Studio shell and workspace specs
|
|
- `PLN-0013` Implement the read-only Code Editor workspace shell and passive surfaces
|
|
- `PLN-0014` Implement the Project Navigator snapshot and read-only file opening flow
|
|
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
|
|
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
|
|
- `docs/specs/studio/2. Studio UI Foundations Specification.md`
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java`
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java`
|
|
|
|
## Takeaways
|
|
|
|
- A good first editor wave can be structurally complete while still being intentionally read-only.
|
|
- Structural project navigation and opened-document content are different state models and should stay separate.
|
|
- Future semantic integration becomes easier when the shell reserves the right surfaces early but refuses to fake capability before the contract exists.
|