---
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.
