# 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.