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 documents including frontend sources

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 controlled editable file-opening model,
• the responsive tab baseline,
• the editor-owned composition surfaces that host save and semantic-read UX,
• the gutter-based active-structure indicator model for semantic editor scopes,
• 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 for the supported document classes classified by prometeu-vfs as editable, including frontend-scoped supported documents,
• 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,
• the integrated frontend semantic-read phase may later add dedicated structural-anchor metadata for exact scope-indicator anchoring,
• frontend semantic presentation contract data comes from frontend-owned metadata published through FrontendSpec,
• 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 the explicit frontend-owned descriptor surfaced by the integrated semantic-read phase. 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,
• controlled-editable in this wave, with supported documents following the canonical access mode provided by prometeu-vfs,
• 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 supported 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 broader IDE automation remains outside this wave.

The workspace must not pretend to offer:

• merge behavior,
• 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 other editable supported 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.

Project-session-owned cross-session tab restoration is accepted for the project-local Studio state wave.

Rules:

• persisted editor restoration state must come from the project-session-owned .studio/ state store rather than from an editor-owned ad hoc file;
• accepted restoration scope in this wave is limited to open tabs and active tab;
• editor layout restoration accepted in this wave may include divider-driven editor sizing, Project Navigator expansion state, and dock-panel configuration such as Outline and Helper open/closed state plus their restored size;
• restoration must degrade safely when a previously open file is missing or unsupported.

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 may be editable when prometeu-vfs classifies them as editable;
• editable scope is limited to the supported textual classes exposed by prometeu-vfs for this wave, including supported frontend sources;
• 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;
• the active indentation policy for editable documents MUST come from project-local setup rather than from file-content heuristics;
• the status-bar indentation chip MUST display the active configured policy, not inferred file contents;
• pressing Tab in an editable document MUST insert spaces according to the active configured indentation width;
• the active indentation policy MUST remain stable while the user edits document contents;
• opening a file whose existing indentation diverges from the configured policy MUST NOT trigger automatic reformatting;
• 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 may be editable when prometeu-vfs grants editable access mode.
• 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.
• Exact anchor positions for semantic scope indicators must come from frontend-owned structural metadata rather than Studio-local text scanning when that metadata is available.
• 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 semantic presentation contract data derived from FrontendSpec.
• Frontend semantic presentation resources must remain frontend-owned and must not be replaced by a Studio-owned generic fallback theme.
• When semantic presentation descriptor data or usable frontend resources are absent, the workspace must continue without semantic highlight for that frontend document.
• The workspace must not surface this condition as a product-facing editor error.
• The workspace must not treat semantic-read over editorial snapshots as authorization for build participation or for bypassing prometeu-vfs access policy.

Inline Hint Rules

Inline hints must be treated as a host-generic editor capability rather than as a PBS-only feature.

The Studio Code Editor must render inline hints only from frontend-owned semantic payloads transported through the integrated semantic-read phase.

The editor must not invent:

• hint existence policy,
• hint text,
• hint categories,
• or host-owned semantic fallback hints.

If a frontend publishes valid inline hints through the accepted semantic-read contract, the editor must render them.

If a frontend does not publish inline hints for a construct, the editor must not synthesize one.

Inline hints are decorative only.

Therefore the editor must ensure that inline hints:

• do not modify document text;
• do not become part of persisted file content;
• do not participate as copied document text;
• do not redefine selection ranges;
• and do not redefine caret movement over the text model.

The completed capability must render inline hints as real inline editor decorations attached to document positions inside the editor flow.

An approximate visual implementation may exist only as an explicit transitional wave.

Any transitional approximation:

• must be documented as transitional;
• must not redefine the final editor contract;
• and must converge to real inline rendering in a later execution step.

When only some inline hint spans remain valid under degraded semantic analysis, the editor must continue rendering those valid spans rather than disabling all inline hints for the document.

Scope Indicator Rules

The default semantic scope-indicator surface in the Code Editor must remain the gutter.

The first active-state wave must render at most two simultaneous semantic indicators:

• activeContainer
• activeScope

The editor must not restore the previous full ancestry stack as the default active-state presentation.

activeScope must be selected as the smallest structural range that contains the caret.

activeContainer must be selected as the immediate structural ancestor of activeScope.

If no valid structural ancestor exists, the editor may omit activeContainer.

The editor must not promote a higher semantic owner such as function, type, or module when a nearer structural ancestor exists.

The concrete visual presentation of activeContainer and activeScope remains frontend-owned. This specification intentionally does not fix:

• colors,
• stroke style,
• dashed versus solid treatment,
• opacity,
• thickness,
• or equivalent visual-emphasis details.

The Studio editor must only preserve the semantic distinction between the two indicator roles.

Exact guide start and end anchoring must consume the dedicated structural-anchor semantic surface defined by the integrated semantic-read specification.

The editor must not treat local brace scanning heuristics as the final production contract for exact anchor placement.

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
• host-owned semantic inline hint policy

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.