378 lines
18 KiB
Markdown
378 lines
18 KiB
Markdown
# 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`](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)
|
|
- [`7. Integrated LSP Semantic Read Phase Specification.md`](7.%20Integrated%20LSP%20Semantic%20Read%20Phase%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 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.
|