# Code Editor Workspace Specification

## Status

Active

## Applies To

- `prometeu-studio`
- the Studio `Code Editor` workspace
- the first read-only editor workspace wave

## Purpose

Define the normative Studio contract for the first `Code Editor` workspace wave.

This specification stabilizes:

- the baseline visual composition of the workspace,
- the `Project Navigator` role and scope,
- the read-only file-opening model,
- the responsive tab baseline,
- the passive `Outline`, helper, and status-bar surfaces,
- and the explicit deferral of write and semantic/LSP behavior.

## Authority and Precedence

This specification extends:

- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)

If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local editor behavior.

## Normative Inputs

The `Code Editor` workspace must assume:

- the Studio shell already mounts `Code Editor` as a baseline workspace,
- the current wave is read-only,
- all project files remain visible in the editor workspace even when only some are frontend-relevant,
- `prometeu.json` plus the selected frontend may identify source roots worth tagging,
- future semantic providers such as LSP may arrive later,
- and the current wave must not depend on write/save or semantic behavior to remain coherent.

This workspace may consume Studio project metadata and Studio-owned workspace framework primitives, but it must not infer a semantic-provider contract beyond keeping the path open for later integration.

## Workspace Model

The `Code Editor` workspace is:

- project-aware,
- file-oriented,
- read-only in this first wave,
- and explicitly not a semantic IDE surface yet.

The workspace must help the user:

- see the full project tree,
- identify frontend-relevant source roots visually,
- open supported files into editor tabs,
- understand the active file context,
- and understand that semantic/editor-automation features are not part of this wave.

The workspace must not pretend to offer:

- save/write behavior,
- dirty state,
- merge behavior,
- active outline semantics,
- or LSP-backed coding assistance.

## Baseline Layout

The baseline workspace layout is:

- a left editor column,
- a central editor work area,
- a lower helper region,
- and a bottom status bar.

The left editor column must be a vertical stack containing:

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

The central editor work area must contain:

- a tab strip at the top,
- and the read-only editor body below it.

The lower helper region is present in this wave only as a passive placeholder.

## Component Ownership Rules

The `Code Editor` workspace must be implemented as a composition root plus child controls/panels rather than one monolithic render surface.

Rules:

- the workspace root should coordinate layout, workspace-level session state, and structural synchronization;
- the `Project Navigator`, tab strip, editor body, reserved `Outline`, helper region, and status bar should exist as explicit local surfaces;
- passive placeholder surfaces must remain visually real without implying unsupported functionality;
- and the first wave should preserve a clean path for later extraction of reusable Studio controls when the surfaces become stable enough to justify that move.

## Project Navigator Rules

### Primary Navigation Unit

- The primary navigation unit is the project file or directory.
- The navigator must cover the whole project rather than only frontend-tagged roots.
- Frontend tagging is supplementary context, not an inclusion filter.

### Structural Snapshot

- The 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.
- Content snapshots are separate and are only required for files that are actually opened in the editor.

### Visibility and Ordering

- All project files and directories must be visible in the navigator.
- Hidden files must be included by default.
- Folders must sort before files.
- Items within those groups must sort alphabetically.

### Frontend-Aware Tagging

- `prometeu.json` plus the selected frontend may be used to tag relevant source roots or source directories.
- That tagging must not hide non-source project files.
- That tagging must not imply semantic/editor-language ownership by the navigator itself.

### Refresh Model

- The navigator must perform one initial refresh when the project opens.
- The navigator must expose a manual refresh action directly on the navigator surface.
- Watcher-driven automatic refresh is explicitly deferred from this wave.

### Unsupported Files

- Unsupported or non-text files may still appear in the navigator.
- Attempting to open such a file must show a simple modal stating that the file is not supported in this wave.
- The workspace must not fake a partial preview to imply unsupported file-format coverage.

## Tabs and File Opening Rules

- Selecting a supported file that is not already open must open it in a new tab.
- The editor must maintain opened-file content in memory for the active Studio session only.
- The tab strip must be responsive rather than fixed to one hardcoded tab count.
- Overflow tabs must remain accessible through an IntelliJ-style overflow control.
- The active tab must remain visible.
- The tab label must use only the file name with extension.

The first wave must not define:

- tab pinning,
- drag-and-drop tab reordering,
- grouped tabs,
- split editors,
- or cross-session tab restoration.

## Read-only File Model

The first `Code Editor` wave is read-only.

Rules:

- supported files may be opened into read-only in-memory buffers,
- the workspace must not write files,
- the workspace must not expose save behavior,
- the workspace must not define dirty tracking,
- and the workspace must not define local merge/conflict behavior against disk changes.

## Outline Rules

- The `Outline` region must exist structurally in this wave.
- It must remain passive.
- It may show a discreet placeholder state.
- It must not fake semantic outline structure before real semantic ownership exists.

## Helper Region Rules

- The helper region must exist structurally in this wave.
- It must remain passive.
- It exists only to stabilize workspace composition and reserve future space.
- It must not become a substitute for the shell-level `Activity` surface.

## Status Bar Rules

The status bar must remain passive in this wave.

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

Its right side must show:

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

For this wave:

- `L:C` may remain a visual placeholder,
- and the read-only lock icon is visual only and does not imply file-permission enforcement.

## Session State Rules

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

That includes at minimum:

- open tabs,
- active tab selection,
- tree expansion state,
- and similar visual editor state.

Persisting that state across Studio executions is deferred.

## Non-Goals

- write/save behavior
- dirty tracking
- merge/conflict resolution
- watcher-driven automatic refresh
- active outline behavior
- helper panel functionality
- semantic analysis surfaces
- LSP integration details
- autocomplete, go-to-definition, symbols, rename, code actions, or semantic diagnostics while typing
- a normative editor event contract in this wave

## Exit Criteria

This specification is complete enough when:

- the read-only first-wave scope is unambiguous,
- the `Project Navigator` and tab responsibilities are explicit,
- placeholder versus functional regions are clearly separated,
- and deferred write/semantic/LSP behavior is clearly outside the first-wave contract.
