217 lines
8.2 KiB
Markdown
217 lines
8.2 KiB
Markdown
---
|
|
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.
|