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 controlled editor write wave for supported non-frontend documents

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 mixed editable and hard read-only file-opening model,
• the responsive tab baseline,
• the editor-owned composition surfaces that host save and semantic-read UX,
• the editor-local save surfaces,
• and the workspace boundary with the integrated frontend semantic-read phase.

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
• 7. Integrated LSP Semantic Read Phase 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 allows editing only for the supported non-frontend document classes classified by prometeu-vfs as editable,
• frontend-scoped supported documents remain hard 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,
• the integrated frontend semantic-read phase may add diagnostics, symbols, outline-facing structure, definition, and highlight for frontend documents,
• and the current wave must not depend on 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. This workspace must consume document access policy and save capability from prometeu-vfs rather than rederiving editability locally.

Workspace Model

The Code Editor workspace is:

• project-aware,
• file-oriented,
• mixed-mode in this wave, with editable supported non-frontend documents and hard read-only frontend documents,
• and not a full 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,
• save editable non-frontend documents through editor-local commands,
• consume frontend semantic-read UX provided through the integrated LSP phase when that phase is active,
• understand the active file context,
• and understand that frontend editing and broader IDE automation remain outside this wave.

The workspace must not pretend to offer:

• merge behavior,
• frontend editing,
• completion,
• rename, code actions, or formatting,
• or editor-owned semantic inference that bypasses the integrated LSP phase.

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 top command bar containing at least Save and Save All,
• a tab strip at the top,
• and the 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.
• Frontend-scoped supported documents may coexist in tabs with editable non-frontend documents.
• 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.

Access-Mode and Save Model

The first Code Editor write wave is controlled rather than universally editable.

Rules:

• the workspace must treat prometeu-vfs as the canonical source of document access mode for supported files;
• the workspace must not infer frontend scope from path heuristics, local UI state, or ad hoc extension checks;
• supported frontend-scoped documents must remain hard read-only;
• editable scope is limited to the supported non-frontend textual classes exposed by prometeu-vfs for this wave;
• the workspace must not allow local editorial mutation for hard read-only frontend documents;
• the workspace must expose save behavior only through an editor-local command bar containing at least Save and Save All;
• the global shell Save menu item must not be the save surface for this wave;
• save intent must route through prometeu-vfs, which remains the owner of persistence policy;
• a frontend hard read-only tab must show a top warning that the file cannot be edited or saved in this wave;
• and the workspace must not define local merge/conflict behavior against disk changes.

Outline Rules

• The Outline region must exist structurally in this wave.
• Before the integrated LSP semantic-read phase is implemented, it may show a discreet placeholder state.
• When the integrated LSP semantic-read phase is active, the Outline region may render frontend document-symbol structure and workspace-symbol-backed navigation owned by that phase.
• The workspace must not fake semantic outline structure before real semantic ownership exists.

Helper Region Rules

• The helper region must exist structurally in this wave.
• Before the integrated LSP semantic-read phase is implemented, it may remain passive.
• It exists only to stabilize workspace composition and reserve future space.
• It may later host diagnostics or related semantic-read detail for frontend documents without changing workspace ownership.
• It must not become a substitute for the shell-level Activity surface.

Integrated Semantic-Read Boundary

• Frontend documents remain hard read-only even when semantic-read capabilities are active.
• Diagnostics, document symbols, workspace symbols, outline-facing structure, definition, and frontend highlight must come through the integrated LSP semantic-read phase rather than from editor-local inference.
• Opened frontend documents must be analyzed from the VFS-owned in-memory snapshot exposed through prometeu-vfs.
• Unopened frontend documents may be analyzed from filesystem-backed state exposed through the same prometeu-vfs boundary.
• Non-frontend highlight may remain Studio-local in this phase.
• Frontend highlight must come from the integrated LSP semantic-read phase and use frontend-owned color semantics.
• The workspace must not treat semantic-read over editorial snapshots as authorization for frontend save, mutation, or build participation.

Status Bar Rules

The status bar must remain mostly 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 access-mode state.

For this wave:

• L:C may remain a visual placeholder,
• editable non-frontend documents may show their current file-type state without implying build participation,
• hard read-only frontend documents must show an explicit read-only state,
• and the status-bar read-only surface should be shaped so it can evolve into a per-file toggle later without requiring a model rewrite.

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,
• document loading responsibilities,
• save persistence policy,
• and build-facing document ownership.

Editable documents may have session-local editorial snapshots while the project session remains open. Those snapshots are editorial only and must not be treated as canonical build input by implication.

Persisting that state across Studio executions is deferred.

Non-Goals

• merge/conflict resolution
• watcher-driven automatic refresh
• public prometeu-vfs event APIs
• helper panel functionality
• editor-owned semantic analysis that bypasses the integrated LSP phase
• frontend editing
• completion, rename, code actions, or formatting
• a normative editor event contract in this wave
• any implication that editor-owned in-memory snapshots participate in the build

Exit Criteria

This specification is complete enough when:

• the controlled write-wave scope is unambiguous,
• the Project Navigator and tab responsibilities are explicit,
• editor-local Save and Save All are part of the normative workspace contract,
• hard frontend read-only behavior is explicit in both warning and status-bar surfaces,
• the workspace boundary with the integrated frontend semantic-read phase is explicit,
• placeholder versus functional regions are clearly separated,
• and excluded frontend editing and completion behavior are clearly outside the current contract.