---
id: DEC-0008
ticket: studio-code-editor-workspace-foundations
title: Read-only foundations for the Studio Code Editor workspace
status: accepted
created: 2026-03-30
accepted: 2026-03-30
agenda: AGD-0010
plans:
  - PLN-0012
  - PLN-0013
  - PLN-0014
tags:
  - studio
  - editor
  - workspace
  - read-only
  - lsp-deferred
---

## Context

The Studio shell already treats `Code Editor` as part of the baseline workspace set, but the current `EditorWorkspace` is still only a hardcoded text area.

AGD-0010 closed the scope of the first editor wave around structural workspace foundations only.
This decision does not close language semantics, compiler integration details, or LSP behavior.
Its job is to define the first stable Studio-owned editor shell that can host real project navigation and file opening without prematurely absorbing semantic ownership.

This decision depends on the current Studio shell and UI foundations:

1. `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
2. `docs/specs/studio/2. Studio UI Foundations Specification.md`

It is also compatible with DEC-0007/DSC-0011, which keeps compiler semantics behind explicit entrypoints and therefore does not force this editor wave to own semantic behavior now.

## Decision

The `studio` domain SHALL implement the first `Code Editor` workspace wave as a read-only editorial foundation.

This wave SHALL establish:

1. the baseline visual composition of the editor workspace,
2. project-tree navigation over the full project,
3. opening project files into responsive tabs,
4. in-memory buffers for opened files in read-only mode,
5. passive placeholder regions for future `Outline` and helper surfaces,
6. a passive status bar with baseline editor metadata,
7. and a future-safe seam for semantic providers such as LSP without making them a dependency of this wave.

This wave SHALL NOT implement:

1. file saving or other write behavior,
2. dirty tracking,
3. local merge/conflict resolution,
4. semantic diagnostics, autocomplete, go-to-definition, symbols, rename, code actions, or other LSP-like features,
5. an active `Outline`,
6. a functional helper panel,
7. or persistence of editor session state across Studio executions.

## Rationale

The correct ownership boundary for this wave is editorial, not semantic.
Studio should own the common workspace composition, project navigation, tabs, and passive file presentation layer.
It should not, in this wave, become the authority for parsing, diagnostics, or language behavior.

This decision also intentionally keeps the first implementation smaller and more stable:

1. read-only mode avoids premature decisions about saving, dirty state, and merge behavior,
2. structural placeholders avoid future layout churn when `Outline`, helper features, and semantic integrations arrive,
3. and a full-project navigator avoids hiding relevant project files behind frontend-only views while still allowing frontend-aware tagging from `prometeu.json`.

## Technical Specification

### 1. Workspace Layout

The `Code Editor` workspace MUST expose the following baseline layout:

1. a left column,
2. a central editor work area,
3. a bottom helper region,
4. and a bottom status bar.

The left column MUST be a vertical stack containing:

1. a functional `Project Navigator` at the top,
2. and a reserved `Outline` region below it.

The `Outline` region MUST exist structurally in this wave, but MUST NOT provide real outline behavior yet.
It MAY show a discreet placeholder state, but it MUST NOT fake semantic structure.

The bottom helper region MUST exist structurally in this wave, but MUST remain passive.
It exists only to stabilize layout and reserve space for future contextual/editor-owned assistance.

### 2. Project Navigator

The `Project Navigator` MUST:

1. show all files and directories in the project,
2. include hidden files by default,
3. order folders before files,
4. order items alphabetically within those groups,
5. and use `prometeu.json` plus the selected frontend only to tag relevant source roots or source directories.

The `Project Navigator` MUST NOT hide non-source project files simply because they are not part of the selected frontend roots.

The `Project Navigator` MUST maintain an in-memory structural snapshot of the project tree for navigation and visual state.
That structural snapshot MUST NOT replace the filesystem as the source of truth.

Refresh rules for this wave are:

1. the tree MUST perform one initial refresh when the project opens,
2. the tree MUST allow manual refresh at any time,
3. the manual refresh control MUST be exposed directly on the `Project Navigator`,
4. and filesystem watching MUST NOT be baseline behavior in this wave.

### 3. File Opening and Tabs

The workspace MUST allow project files to be opened into editor tabs.

Tab rules are:

1. selecting a file that is not already open MUST open it in a new tab,
2. the tab strip MUST be responsive,
3. the visible tab count MUST be driven by available width rather than a fixed numeric limit,
4. overflow tabs MUST remain reachable through an IntelliJ-style overflow control,
5. the active tab MUST remain visible,
6. and the tab label MUST use only the file name with extension.

This wave MUST NOT define pinning, drag-and-drop tab reordering, grouped tabs, split editors, or session-persistent tab restoration.

### 4. Read-only File Model

This wave MUST operate in read-only mode.

Opened files MAY be loaded into in-memory buffers for display and navigation, but those buffers MUST remain read-only in this wave.

Consequences:

1. the editor MUST NOT write files,
2. the editor MUST NOT provide save behavior,
3. the editor MUST NOT define dirty tracking,
4. and the editor MUST NOT define local merge behavior against disk changes.

Unsupported or non-text files MAY still appear in the `Project Navigator`, but attempting to open them MUST show a simple modal stating that the file is not supported in this wave.

### 5. Status Bar

The workspace MUST include a passive status bar.

Its left side MUST show the breadcrumb path of the active file, such as `proj > src > file.pbs`.

Its right side MUST show:

1. `L:C`,
2. line separator,
3. tabs/spaces mode,
4. file extension or language,
5. and a read-only lock icon.

For this wave:

1. `L:C` MAY remain a visual placeholder,
2. and the lock icon MUST be visual only, with no functional enforcement beyond signaling read-only intent.

### 6. Placeholder Surfaces

The `Outline` region and the helper region MUST remain passive in this wave.

Rules:

1. they exist to stabilize composition and reserve future workspace surfaces,
2. they MUST NOT claim semantic capabilities they do not yet have,
3. and they MUST NOT become dumping grounds for global shell logging.

### 7. Session State

Any visual/editorial state in this wave is session-local only.

This includes at minimum:

1. open tabs,
2. active tab selection,
3. tree expansion state,
4. and similar visual workspace state.

This decision MUST NOT require persistence of that state across Studio executions.

### 8. Deferred Scope

The following are explicitly deferred and MUST NOT be treated as part of this wave:

1. write/save behavior,
2. dirty state,
3. merge/conflict resolution,
4. watcher-driven automatic filesystem synchronization,
5. semantic analysis surfaces,
6. LSP integration details,
7. autocomplete, go-to-definition, symbols, rename, code actions, and semantic diagnostics while typing,
8. active outline behavior,
9. helper panel functionality,
10. and a normative editor event contract.

If implementation needs local events internally, they MAY exist as implementation detail, but they MUST NOT be treated as the normative output of this decision.

## Constraints

1. This decision is Studio-owned and applies to the `studio` domain, not to compiler semantic ownership.
2. This decision MUST remain compatible with future semantic providers, including LSP.
3. This decision MUST NOT infer or hardcode a semantic provider contract prematurely.
4. This decision MUST preserve compatibility with existing Studio shell and UI foundations specs.
5. Any future move from read-only mode to editable mode MUST occur through a new explicit decision or an explicit revision of this decision.

## Revision Log

- 2026-03-30: Initial draft from AGD-0010.
- 2026-03-30: Accepted and decomposed into PLN-0012, PLN-0013, and PLN-0014.