prometeu-studio/docs/specs/studio/5. Code Editor Workspace Specification.md

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
• 2. Studio UI Foundations Specification.md
• 3. Studio Components Module Specification.md
• 6. Project Document VFS Specification.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. This workspace must consume project tree and document data through prometeu-vfs rather than through editor-owned direct filesystem readers.

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 workspace root should consume project-session-owned document services such as prometeu-vfs rather than owning their lifecycle locally;
• 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 consume a structural project-tree entity provided by prometeu-vfs.
• That structural tree 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 through prometeu-vfs.
• The navigator may request more targeted tree refresh operations than a full-tree reload when the prometeu-vfs contract provides them.

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.
• Rendering those tags remains a Studio UI concern even when the source data comes from prometeu-vfs.

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 and route that request through prometeu-vfs.
• Watcher-driven automatic refresh is explicitly deferred from this wave.

Unsupported Files

• Unsupported or non-text files may still appear in the navigator.
• File support and unsupported-file classification belong to prometeu-vfs.
• 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.
• File opening must resolve document content through prometeu-vfs.
• 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.

The following remain outside editor-owned session state:

• project-session ownership of prometeu-vfs,
• structural project-tree data returned by prometeu-vfs,
• support classification rules,
• and document loading responsibilities.

Persisting that state across Studio executions is deferred.

Non-Goals

• write/save behavior
• dirty tracking
• merge/conflict resolution
• watcher-driven automatic refresh
• public prometeu-vfs event APIs
• 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.