implements PLN-0064
This commit is contained in:
@@ -44,15 +44,10 @@ The left workspace selector remains fixed in the baseline Studio shell.
|
||||
|
||||
The baseline workspace set includes:
|
||||
|
||||
- Code Editor;
|
||||
- Asset Management;
|
||||
- Debugger/Profiler;
|
||||
- Shipper, temporarily represented by the current `BuilderWorkspace`.
|
||||
|
||||
Workspace-local behavior for the first `Code Editor` wave is defined in:
|
||||
|
||||
- `5. Code Editor Workspace Specification.md`
|
||||
|
||||
`BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface.
|
||||
|
||||
## Workspace Architecture Model
|
||||
@@ -71,7 +66,7 @@ Baseline workspace architecture rules are:
|
||||
The shell must not encourage a workspace model where every interaction falls back to whole-workspace refresh.
|
||||
|
||||
Detailed local workspace composition remains workspace-owned.
|
||||
For example, `Code Editor`-local layout, navigator behavior, tab rules, passive placeholder surfaces, document access-mode behavior, and editor-local save surfaces are not shell-global rules and must be defined by the workspace-local editor specification.
|
||||
For example, `Assets`-local navigator behavior, detail-pane composition, and mutation flows are not shell-global rules and must be defined by the workspace-local specifications that still exist.
|
||||
|
||||
Project-session boundaries may still exist above a workspace when the state must remain alive while the project window stays open.
|
||||
|
||||
|
||||
@@ -1,377 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,235 +0,0 @@
|
||||
# Project Document VFS Specification
|
||||
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-vfs`
|
||||
- `prometeu-studio`
|
||||
- the Studio project-document boundary for the first controlled Code Editor write wave
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the normative Studio contract for `prometeu-vfs` as the project-document boundary consumed by Studio workspaces.
|
||||
|
||||
This specification stabilizes:
|
||||
|
||||
- `prometeu-vfs` module role,
|
||||
- project-session ownership,
|
||||
- the filesystem-backed first-wave contract,
|
||||
- structural tree and document access responsibilities,
|
||||
- canonical frontend scope and access policy ownership,
|
||||
- editorial snapshot and save ownership for editable supported documents including frontend sources,
|
||||
- the semantic-read consumer boundary used by the integrated LSP phase,
|
||||
- the RPC-first public API baseline,
|
||||
- and explicit first-wave exclusions such as public event publication and watchers.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification extends:
|
||||
|
||||
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
|
||||
|
||||
If this document conflicts with shell-wide Studio rules, the shell specification controls shell-wide behavior and this document controls the project-document boundary contract.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
`prometeu-vfs` must assume:
|
||||
|
||||
- the current migration wave carries only the Code Editor capabilities that already exist today,
|
||||
- the initial backend is filesystem-backed,
|
||||
- the boundary is project-scoped rather than product-global,
|
||||
- the boundary must outlive workspace focus changes for an opened project,
|
||||
- Studio UI remains the owner of visual tree state and error presentation,
|
||||
- and the integrated `prometeu-lsp` phase consumes this boundary as a semantic-read client rather than as a persistence owner.
|
||||
|
||||
`prometeu-vfs` must not infer:
|
||||
|
||||
- watcher-driven refresh in this wave,
|
||||
- public event API exposure in this wave,
|
||||
- build participation for editorial snapshots by implication,
|
||||
- or ownership over non-Studio domains such as packer assets.
|
||||
|
||||
## Module Role
|
||||
|
||||
`prometeu-vfs` is:
|
||||
|
||||
- the Studio project-document boundary,
|
||||
- the owner of project structural tree data for the covered scope,
|
||||
- the owner of project document resolution for the covered scope,
|
||||
- the owner of file support and unsupported-file classification for the covered scope,
|
||||
- the owner of document access policy for the covered scope,
|
||||
- the owner of save persistence for editable documents in this wave,
|
||||
- and the required path through which Studio accesses project-document filesystem state in this wave.
|
||||
|
||||
`prometeu-vfs` is not:
|
||||
|
||||
- a visual tree control,
|
||||
- a Studio shell replacement,
|
||||
- a product-wide universal filesystem layer,
|
||||
- or a public event transport in this wave.
|
||||
|
||||
## Project Session Ownership
|
||||
|
||||
The primary `prometeu-vfs` instance must belong to the Studio project session.
|
||||
|
||||
Rules:
|
||||
|
||||
- a project-scoped `prometeu-vfs` instance must be created when a Studio project session is opened;
|
||||
- that instance must remain alive while the project session remains open;
|
||||
- switching workspace focus must not destroy or recreate the project-document state by default;
|
||||
- the `Code Editor` workspace must consume the session-owned `prometeu-vfs` instance rather than owning the boundary lifecycle itself;
|
||||
- the project-session scope must cover only the opened project.
|
||||
|
||||
## Filesystem Access Rules
|
||||
|
||||
For the scope covered by this specification, Studio must access the project filesystem through `prometeu-vfs`.
|
||||
|
||||
Rules:
|
||||
|
||||
- the first implementation must be filesystem-backed;
|
||||
- direct filesystem reads for project tree and document loading must not remain a workspace-owned responsibility in the Code Editor;
|
||||
- this rule does not grant `prometeu-vfs` ownership over unrelated domains or unrelated filesystem responsibilities elsewhere in the product.
|
||||
|
||||
## Structural Tree Contract
|
||||
|
||||
`prometeu-vfs` must expose a structural representation of the project tree.
|
||||
|
||||
Rules:
|
||||
|
||||
- the structural tree must cover project content only;
|
||||
- the structural tree must contain structural and documentary data only;
|
||||
- the structural tree must not contain visual presentation state;
|
||||
- the structural tree must not contain navigator chrome decisions;
|
||||
- the structural tree may include structural metadata useful to Studio consumers;
|
||||
- consumers may request narrower refreshes than a full-tree reload when the request remains within the project boundary.
|
||||
|
||||
The following concerns remain outside `prometeu-vfs`:
|
||||
|
||||
- visual expansion state,
|
||||
- selection state,
|
||||
- focus state,
|
||||
- reveal or scroll behavior,
|
||||
- icon choice,
|
||||
- and other view-model concerns of the navigator UI.
|
||||
|
||||
## Document Access Contract
|
||||
|
||||
`prometeu-vfs` must own document resolution for the covered Studio scope.
|
||||
|
||||
Rules:
|
||||
|
||||
- opening a supported file in the Code Editor must go through `prometeu-vfs`;
|
||||
- the returned document content must describe only project-session document state for the opened project;
|
||||
- `prometeu-vfs` must classify each supported document as at least editable or hard `read-only`;
|
||||
- unsupported documents must remain distinguishable from supported `read-only` and supported editable documents;
|
||||
- `prometeu-vfs` must own editable in-memory editorial snapshots for the current Studio session;
|
||||
- save operations for editable documents in this wave must persist those editorial snapshots to disk through `prometeu-vfs`;
|
||||
- Studio consumers must treat `prometeu-vfs` access policy as canonical rather than rederiving editability locally;
|
||||
- and editorial snapshots must remain outside build-facing document state.
|
||||
|
||||
## Frontend Scope Contract
|
||||
|
||||
Frontend scope must be decided canonically inside `prometeu-vfs`.
|
||||
|
||||
Rules:
|
||||
|
||||
- `FrontendSpec.allowedExtensions` is the source of truth for frontend scope in this wave;
|
||||
- the VFS document contract must expose a canonical frontend-compatible `typeId` or equivalent scope marker derived from that source of truth;
|
||||
- consumers must not infer frontend scope from raw dynamic language identifiers, path heuristics, or local UI extension checks;
|
||||
- frontend-scoped supported documents must be editable in this wave when they are supported by the current frontend;
|
||||
- the initial editable set is limited to the currently supported textual classes represented as `text`, `json`, `ndjson`, `bash`, and supported frontend source documents resolved from `FrontendSpec.allowedExtensions`;
|
||||
- and no additional editable class may be inferred by implementation convenience during this wave.
|
||||
|
||||
## Document Access Context
|
||||
|
||||
`prometeu-vfs` must reserve a single access-context entity for document-access-related values.
|
||||
|
||||
Rules:
|
||||
|
||||
- the access-context entity may remain session-local in this wave;
|
||||
- it must already support lookup and mutation under current demand;
|
||||
- future persistence may be added later without redesigning the access model;
|
||||
- and the current reservation must not be treated as authorization for build participation or broader product-wide state ownership.
|
||||
|
||||
## Semantic-Read Consumer Boundary
|
||||
|
||||
`prometeu-vfs` must remain the source-of-truth document substrate consumed by the integrated LSP semantic-read phase.
|
||||
|
||||
Rules:
|
||||
|
||||
- opened frontend documents must be exposed to `prometeu-lsp` from the in-memory editorial snapshot held by `prometeu-vfs`, including dirty snapshots not yet saved to disk;
|
||||
- unopened frontend documents may be exposed to `prometeu-lsp` from filesystem-backed state through the same boundary;
|
||||
- `prometeu-lsp` must not bypass `prometeu-vfs` with ad hoc filesystem reads inside Studio UI code;
|
||||
- `prometeu-lsp` must not become the owner of save, persistence, or access policy;
|
||||
- semantic analysis over editorial snapshots must remain separate from build-facing document ownership;
|
||||
- and this boundary must remain suitable for frontend diagnostics, symbols, definition, and highlight without implying frontend edit rights.
|
||||
|
||||
## Support and Plugin Rules
|
||||
|
||||
Support and unsupported-file decisions belong to `prometeu-vfs`.
|
||||
|
||||
Rules:
|
||||
|
||||
- file support classification must be decided inside `prometeu-vfs`;
|
||||
- plugin or handler resolution for supported file access must be decided inside `prometeu-vfs`;
|
||||
- Studio UI may render the resulting success or failure state, but it must not own the classification rule itself.
|
||||
|
||||
## Communication Model
|
||||
|
||||
The official first-wave `prometeu-vfs` API is RPC-oriented.
|
||||
|
||||
Rules:
|
||||
|
||||
- commands and queries are the public API baseline for this wave;
|
||||
- internal runtime events may exist inside `prometeu-vfs`;
|
||||
- those events must remain internal in this wave;
|
||||
- internal events must not be promoted to public API by inference during planning or implementation.
|
||||
|
||||
## Refresh and Watchers
|
||||
|
||||
Refresh remains manual in this wave.
|
||||
|
||||
Rules:
|
||||
|
||||
- Studio consumers may request manual refresh through `prometeu-vfs`;
|
||||
- watcher-driven automatic refresh is deferred;
|
||||
- file watching must not be introduced implicitly while implementing this specification.
|
||||
|
||||
## Cross-Domain Boundary
|
||||
|
||||
`prometeu-vfs` belongs to the Studio domain.
|
||||
|
||||
Rules:
|
||||
|
||||
- `prometeu-vfs` serves `prometeu-lsp` as a consumer-facing substrate for the semantic-read phase;
|
||||
- `prometeu-lsp` remains a separate layer and must not be renamed into `prometeu-vfs`;
|
||||
- `prometeu-vfs` must not absorb packer responsibilities;
|
||||
- `prometeu-vfs` must not redefine asset ownership;
|
||||
- extending this boundary outside project-document concerns requires a new decision.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- public event publication
|
||||
- watcher-driven refresh
|
||||
- dirty tracking
|
||||
- merge or conflict handling
|
||||
- non-project content snapshots
|
||||
- a generic product-wide filesystem abstraction
|
||||
- treating editorial snapshots as canonical build input
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- `prometeu-vfs` ownership is clearly separated from shell and workspace UI ownership,
|
||||
- the project-session lifecycle rule is unambiguous,
|
||||
- the structural tree contract is explicitly non-visual,
|
||||
- frontend scope and access policy ownership are explicit,
|
||||
- editable supported-document snapshot and save ownership are explicit,
|
||||
- the semantic-read consumer boundary with `prometeu-lsp` is explicit,
|
||||
- the RPC-first public API rule is explicit,
|
||||
- and deferred public events and watchers are clearly out of scope.
|
||||
@@ -1,183 +0,0 @@
|
||||
# Integrated LSP Semantic Read Phase Specification
|
||||
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-studio`
|
||||
- `prometeu-vfs`
|
||||
- `prometeu-lsp`
|
||||
- the integrated frontend semantic phase in the Studio `Code Editor` workspace
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the normative Studio contract for the integrated frontend semantic-read phase that arrives before any frontend editing release.
|
||||
|
||||
This specification stabilizes:
|
||||
|
||||
- the phase boundary between semantic ownership and frontend editing ownership,
|
||||
- the ownership relationship between `prometeu-vfs`, `prometeu-lsp`, and the Studio editor,
|
||||
- the minimum semantic capability set for frontend documents,
|
||||
- the dedicated semantic surface used for structural anchors and guide-aware editor structure,
|
||||
- the packaging expectations for the public `prometeu-lsp` API surface,
|
||||
- and the explicit exclusions that remain outside this phase.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification extends:
|
||||
|
||||
- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
|
||||
- [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md)
|
||||
|
||||
If this document conflicts with shell-wide Studio rules, shell rules control shell behavior, the Code Editor specification controls workspace-local editor UX, the VFS specification controls document-boundary ownership, and this document controls the integrated semantic-read phase itself.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
The integrated semantic-read phase must assume:
|
||||
|
||||
- frontend-scoped documents may be editable under the controlled write wave exposed by `prometeu-vfs`,
|
||||
- editable supported documents remain governed by the controlled write wave,
|
||||
- `FrontendSpec.allowedExtensions` remains the source of truth for frontend scope,
|
||||
- `FrontendSpec` is the canonical source of frontend semantic presentation contract data,
|
||||
- `prometeu-vfs` owns document state, snapshots, persistence, and access policy,
|
||||
- and semantic-read over editorial snapshots must remain separate from build-facing ownership.
|
||||
|
||||
## Phase Boundary
|
||||
|
||||
This phase is a semantic phase for frontend documents, not an ownership phase for frontend editing.
|
||||
|
||||
Rules:
|
||||
|
||||
- no capability in this phase may override `prometeu-vfs` access policy, save policy, or snapshot ownership;
|
||||
- completion, rename, code actions, and formatting remain outside this phase.
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
- `prometeu-vfs` owns document state, access policy, editorial snapshots, and persistence.
|
||||
- `prometeu-lsp` is a semantic consumer above `prometeu-vfs`.
|
||||
- the Studio `Code Editor` owns UX surfaces that render semantic-read output.
|
||||
- each frontend owns its semantic vocabulary and semantic presentation resources.
|
||||
- build-facing document ownership remains outside this phase.
|
||||
|
||||
`prometeu-lsp` must not become the owner of:
|
||||
|
||||
- save,
|
||||
- persistence,
|
||||
- document access policy,
|
||||
- frontend semantic presentation assets,
|
||||
- or frontend edit-right release.
|
||||
|
||||
## Document Source-of-Truth Rules
|
||||
|
||||
- opened frontend documents must be analyzed from the in-memory snapshot exposed by `prometeu-vfs`;
|
||||
- unopened frontend documents may be analyzed from filesystem-backed state exposed through the same `prometeu-vfs` boundary;
|
||||
- Studio UI code must not bypass `prometeu-vfs` with ad hoc file loading for semantic-read behavior;
|
||||
- semantic-read over editorial snapshots must not be treated as canonical build input by implication.
|
||||
|
||||
## Minimum Capability Set
|
||||
|
||||
The minimum semantic capability set of this phase must include:
|
||||
|
||||
- diagnostics for frontend documents;
|
||||
- document symbols for frontend documents;
|
||||
- workspace symbols for frontend documents;
|
||||
- outline-facing structural symbol data;
|
||||
- go-to-definition for frontend documents;
|
||||
- frontend semantic highlight.
|
||||
|
||||
The phase may ship the dedicated structural-anchor surface after the baseline capability set is stable, but Studio and frontend implementations must treat that surface as the canonical source of exact scope-indicator anchoring once it exists.
|
||||
|
||||
The phase may also ship a dedicated inline-hint semantic surface.
|
||||
|
||||
Once shipped, frontend and Studio implementations must treat that surface as the canonical source of decorative inline hint payloads.
|
||||
|
||||
## Highlight Ownership Rules
|
||||
|
||||
- frontend highlight must come from semantic information provided through `prometeu-lsp`;
|
||||
- frontend highlight must use frontend-owned semantic presentation contract data derived from `FrontendSpec`;
|
||||
- `prometeu-lsp` must expose a dedicated semantic presentation descriptor derived from the resolved `FrontendSpec`;
|
||||
- that descriptor must remain simple and include frontend-owned `semanticKeys` plus frontend-owned `resources` in the same message surface;
|
||||
- `prometeu-lsp` must not collapse frontend semantic keys into host-owned generic categories;
|
||||
- Studio must project semantic keys mechanically to CSS classes without semantic translation;
|
||||
- frontend semantic presentation resources must remain under frontend `resources/` and be resolved like ordinary Java resources;
|
||||
- when semantic presentation descriptor data or usable resources are absent, Studio must continue without semantic highlight;
|
||||
- this condition must not become a product-facing Studio error and may at most produce normal development logs;
|
||||
- non-frontend highlight may remain on the existing Studio-local highlighting path in this phase.
|
||||
|
||||
## Inline Hint Ownership Rules
|
||||
|
||||
- frontend inline hints must come from semantic information provided through `prometeu-lsp`;
|
||||
- frontend hint existence and hint payload semantics remain frontend-owned;
|
||||
- `prometeu-lsp` must expose a dedicated transport contract for inline hints rather than relying on Studio-local inference;
|
||||
- `prometeu-lsp` must preserve deterministic anchor information required for host rendering;
|
||||
- `prometeu-lsp` must not invent host-owned hint policy when a frontend does not publish hints;
|
||||
- Studio must render transported hints mechanically as host decorations rather than as document text;
|
||||
- valid inline hint spans must survive partial degradation when the frontend can still produce them;
|
||||
- invalid or missing hint spans may be omitted locally;
|
||||
- Studio must not disable all inline hints for a document solely because some hint spans are unavailable.
|
||||
|
||||
## Structural Anchor Semantic Surface
|
||||
|
||||
Exact structural anchoring for editor scope indicators must not be overloaded into `documentSymbols`.
|
||||
|
||||
`documentSymbols` remains the outline and navigation surface.
|
||||
|
||||
Guide-oriented structure must be exposed through a dedicated semantic surface for structural anchors and related guide metadata.
|
||||
|
||||
That dedicated surface must be frontend-owned and language-agnostic.
|
||||
|
||||
The contract must describe generic structural positions rather than PBS-specific brace semantics.
|
||||
|
||||
The surface must be able to represent structures whose boundaries are expressed by:
|
||||
|
||||
- braces;
|
||||
- keywords;
|
||||
- indentation-derived blocks;
|
||||
- or mixed delimiter schemes.
|
||||
|
||||
At minimum, the dedicated structural-anchor surface must be able to communicate:
|
||||
|
||||
- structural ranges that can participate in active-scope selection;
|
||||
- immediate parentage or equivalent information needed to recover the nearest ancestor relationship;
|
||||
- exact structural anchor positions used for guide start and end placement;
|
||||
- enough structural identity to distinguish the active structural range from its immediate container.
|
||||
|
||||
The semantic-read contract must not require Studio to scan source text in order to discover the final structural anchor positions.
|
||||
|
||||
Temporary local heuristics may exist only as development aids. They must not become the canonical production contract.
|
||||
|
||||
The exact serialized schema of this dedicated surface may evolve in implementation plans, but any accepted schema must preserve the invariants above.
|
||||
|
||||
## Packaging Rules
|
||||
|
||||
The public `prometeu-lsp` API should follow flat packaging similar to `prometeu-packer-api`.
|
||||
|
||||
Rules:
|
||||
|
||||
- public contract surfaces should remain shallow and explicit;
|
||||
- packages such as `dtos`, `messages`, and `events` are the preferred shape for public API grouping where those surfaces exist;
|
||||
- deep public packaging by internal implementation concern should be avoided;
|
||||
- runtime or implementation layering may exist internally, but it must not leak into the public contract surface by default.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- frontend save policy
|
||||
- completion
|
||||
- rename
|
||||
- code actions
|
||||
- formatting
|
||||
- build participation inferred from editorial snapshots
|
||||
- external-editor compatibility requirements
|
||||
- Studio-owned semantic hint generation
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- the semantic-read versus frontend-editing phase boundary is explicit,
|
||||
- `prometeu-vfs` and `prometeu-lsp` ownership remains unambiguous,
|
||||
- the minimum semantic capability set is explicit,
|
||||
- frontend and non-frontend highlight ownership is clearly separated,
|
||||
- and the excluded editing and completion capabilities remain unambiguous.
|
||||
@@ -22,7 +22,6 @@ This specification implements the accepted decision for project-local Studio sta
|
||||
It extends:
|
||||
|
||||
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
|
||||
|
||||
## Core Rules
|
||||
|
||||
@@ -31,7 +30,7 @@ It extends:
|
||||
3. The main session-restoration store MUST remain a single file at `.studio/state.json`.
|
||||
4. The main session-restoration store MUST be versioned.
|
||||
5. The main session-restoration store MUST load when the project session opens.
|
||||
6. Restorable shell and editor state accepted by this wave MUST restore when the project shell mounts.
|
||||
6. Restorable shell state accepted by this wave MUST restore when the project shell mounts.
|
||||
7. The main session-restoration store MUST save when the project shell or project session closes.
|
||||
8. Missing, invalid, or schema-incompatible session-restoration state MUST fall back to safe default values and MUST NOT block project open.
|
||||
9. Project-local setup configuration MUST live in a separate file at `.studio/setup.json`.
|
||||
@@ -44,13 +43,11 @@ The main session-restoration store MUST include:
|
||||
|
||||
- `shellLayout`
|
||||
- `openShellState`
|
||||
- `editorRestoration`
|
||||
|
||||
Wave-1 accepted meaning is:
|
||||
|
||||
- `shellLayout`: restorable layout state already accepted by implementation, including divider positions and equivalent layout proportions for accepted workspaces such as `Assets` and `Code Editor`, `Project Navigator` expansion state, and editor dock-panel open/closed plus restored-size configuration;
|
||||
- `shellLayout`: restorable layout state already accepted by implementation, including divider positions and equivalent layout proportions for accepted workspaces such as `Assets`;
|
||||
- `openShellState`: which workspace or equivalent shell-owned project view was open;
|
||||
- `editorRestoration`: open editor tabs and active tab.
|
||||
|
||||
## Project-Local Setup Configuration
|
||||
|
||||
@@ -61,8 +58,8 @@ Rules:
|
||||
- project-local setup MUST live in `.studio/setup.json`;
|
||||
- project-local setup MUST be treated as project configuration rather than session state;
|
||||
- project-local setup MAY contain runtime-oriented values such as the Prometeu runtime path;
|
||||
- project-local setup MUST own the project-wide editor indentation policy;
|
||||
- the editor indentation policy MUST define at least indentation mode and indentation width;
|
||||
- project-local setup MAY continue carrying project-wide indentation policy defaults for future code-tooling integrations;
|
||||
- the indentation policy MUST define at least indentation mode and indentation width;
|
||||
- when setup does not provide an explicit indentation policy, consumers MUST resolve it to `spaces` with width `4`;
|
||||
- project-local setup MAY grow with additional manual or automatic configuration keys over time;
|
||||
- consumers such as `Play` MUST read project-local setup from the dedicated setup file rather than from `.studio/state.json`;
|
||||
|
||||
@@ -54,10 +54,7 @@ The current Studio core corpus is:
|
||||
2. [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
3. [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
|
||||
4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md)
|
||||
5. [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)
|
||||
6. [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md)
|
||||
7. [`7. Integrated LSP Semantic Read Phase Specification.md`](7.%20Integrated%20LSP%20Semantic%20Read%20Phase%20Specification.md)
|
||||
8. [`8. Project-Local Studio State Specification.md`](8.%20Project-Local%20Studio%20State%20Specification.md)
|
||||
5. [`8. Project-Local Studio State Specification.md`](8.%20Project-Local%20Studio%20State%20Specification.md)
|
||||
|
||||
## Reading Order
|
||||
|
||||
@@ -67,19 +64,14 @@ Recommended order:
|
||||
2. shared UI foundations;
|
||||
3. components module policy;
|
||||
4. assets workspace behavior;
|
||||
5. project document VFS boundary;
|
||||
6. code editor workspace behavior;
|
||||
7. integrated LSP semantic-read behavior;
|
||||
8. project-local Studio state behavior.
|
||||
5. project-local Studio state behavior.
|
||||
|
||||
## Current Wave Notes
|
||||
|
||||
The current `Code Editor` wave is not globally read-only anymore.
|
||||
The embedded Studio code-editor stack was removed by `DEC-0031`.
|
||||
|
||||
Normative reminders:
|
||||
|
||||
- editable scope is limited to supported non-frontend textual documents classified by `prometeu-vfs`;
|
||||
- frontend-scoped supported documents remain hard `read-only`;
|
||||
- the editor-local `Save` and `Save All` surfaces belong to the `Code Editor` workspace rather than the shell;
|
||||
- editorial in-memory snapshots remain outside build-facing state;
|
||||
- frontend semantic-read capability lands before any frontend editing release and is documented by the integrated LSP phase specification.
|
||||
- the active Studio workspace corpus is `Assets`, `Debug`, and `Shipper`;
|
||||
- project-local Studio session state remains normative and is owned by `StudioProjectSession`;
|
||||
- any future external-editor backend or replacement language-service architecture requires a new accepted decision before new Studio specs are introduced.
|
||||
|
||||
Reference in New Issue
Block a user