256 lines
9.1 KiB
Markdown
256 lines
9.1 KiB
Markdown
# 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)
|
|
- [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%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.
|
|
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.
|